{"openapi":"3.1.0","info":{"title":"Payments API v3","description":"References for Payments API v3\n","version":"1","license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://api.truelayer-sandbox.com","description":"Sandbox server"},{"url":"https://api.truelayer.com","description":"Production server"}],"tags":[{"name":"Payments","description":"Payments endpoints to create and manage payments resources. You can use this resource to create payments to\na GBP or a EUR account (limited to available countries), or your merchant account managed by TrueLayer.\n"},{"name":"Payment links","description":"Payment Links endpoints to create and manage payment links resources. You can use this resource to create payment links to\nshare with the PSUs so they can make payments into your merchant account managed by TrueLayer.\n"},{"name":"Payments providers","description":"Endpoints to retrieve payments providers.\n"},{"name":"Payouts","description":"Payouts endpoints facilitate money movement from your TrueLayer managed merchant account to\npayment sources, or arbitrary external accounts\n"},{"name":"Merchant accounts","description":"Endpoints to interact with your TrueLayer managed merchant account\n"},{"name":"Mandates","description":"# Payment Mandates\n\nMandates are a payment source.\n\nA Payment Mandate is a single consent, given by a PSU, to authorise repeated payments on a schedule\nor ad-hoc basis. Depending on the use case, the PSU may not be required to authorise payments against\nan existing mandate.\n\nThe consent given for a mandate will always include the same debtor (or remitter) account. Depending on\nthe type of Mandate, the creditor (or beneficiary) account may or may not always be the same.\n\n## VRP (Sweeping/Commercial)\n\nVariable Recurring Payments (VRP) are an Open Banking specification allowing a PSU to\nauthorize repeated payments from their bank account to another account they own.\n\nThe PSU only needs to give this consent once. Payments against this consent can then be\ninitiated by a PSP to move funds between accounts with no further input from the PSU.\n\nWhen establishing this consent, the PSU will agree to certain parameters that will enforce\nlimits such as how long the consent will be valid for and what maximum value of transfer will be\nallowed over the consent lifetime. Other limits can be set for timeframes within this lifetime.\n\nA new VRP Mandate is created by calling `POST /v3/mandates`, using a bearer token.\n\nOpenBanking VRP Mandates require the end user to go through an authorization flow -\nthe status of the newly created mandate will therefore be `authorization_required`.\nThe mandate resource will contain a `mandate_token` that can be safely shared with the UI,\nwhere the authorization flow will be taking place.\n\nThe UI can use the `mandate_token` to kick off the **authorization journey**.\nAuthorizing an OpenBanking mandate usually requires multiple **actions**:\n  - collect information from the end user (e.g. select a banking institution);\n  - redirect to a bank's website or mobile app;\n  - etc.\n\nThe UI must specify, using `POST /v3/mandates/authorization_flow`, which **actions** it supports.\nConfiguration parameters can be specified for each action type - e.g. what `return_uri` to\nuse for a `redirect` step, if \"direct return\" is enabled (regulated merchant), etc.\n\nAfter the call to `POST /v3/mandates/authorization_flow`, the mandate status will transition to `authorizing`.\nThe UI must now inspect the `authorization_flow.actions.next` field in the mandate resource and submit the required\ninformation via `POST /v3/mandates/authorization_flow/actions`.\n\nThe mandate might then transition into `authorized`, or stay in `authorizing` with a different next action.\n\nShould the PSU and/or Provider decide to reject the authorization, the mandate status will\ntransition to `revoked`.\n\nPayments can only be made against a mandate once it has transitioned to `authorized`. Those payments\nwill then need to fall within the boundaries set by the consent parameters.\n\nShould the PSU and/or Provider decide to reject the authorization, the mandate status will\ntransition to `revoked`.\n"}],"paths":{"/v3/payment-links":{"post":{"tags":["Payment links"],"summary":"Create payment link","operationId":"create-payment-link","description":"Create a new payment link\n\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["payments","payment_links:create"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatePaymentLink"}}}},"responses":{"201":{"description":"Payment link","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatedPaymentLink"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payment-links/{id}":{"get":{"tags":["Payment links"],"summary":"Get payment link","operationId":"get-payment-link","description":"Retrieves payment link details.\n\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["payments","payment_links"]}],"parameters":[{"in":"path","name":"id","description":"ID of the payment link","schema":{"$ref":"#/components/schemas/PaymentLinkId"},"required":true}],"responses":{"200":{"description":"Payment Link","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetPaymentLink"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Link Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payment-links/{id}/payments":{"get":{"tags":["Payment links"],"summary":"Get payments","operationId":"get-payment-link-payments","description":"List all the payments associated with the payment link.\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"in":"path","name":"id","description":"ID of the payment link","schema":{"$ref":"#/components/schemas/PaymentLinkId"},"required":true},{"in":"query","name":"cursor","schema":{"$ref":"#/components/schemas/Cursor"},"required":false},{"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/Limit"},"required":false}],"responses":{"200":{"description":"Payments list","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetPaymentLinkPayments"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Link Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments":{"post":{"tags":["Payments"],"summary":"Create payment","operationId":"create-payment","description":"Create a new payment \n\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/PsuIpAddressHeader","description":"Used to collect and record end-user IP address.\nThe first IP address in the [list](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) will be used as the end-user IP address.\nThis header is only considered if the authorization_flow object in the request body is specified.\n"},{"$ref":"#/components/parameters/DeviceUserAgentHeader","description":"Used to improve end-user's authentication experience based on device type.\nIf omitted, the `User-Agent` header will be used instead.\nThis header is only considered if the authorization_flow object in the request body is specified.\n"}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatePayment"}}}},"responses":{"201":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatedPayment"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/authorization-flow":{"post":{"tags":["Payments"],"summary":"Start authorization flow","operationId":"start-payment-authorization-flow","description":"Start the authorization flow for a payment.\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to fetch;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"$ref":"#/components/parameters/PsuIpAddressHeader"},{"$ref":"#/components/parameters/DeviceUserAgentHeader"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/StartPaymentAuthorizationFlow"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/authorization-flow/actions/provider-selection":{"post":{"tags":["Payments"],"summary":"Submit provider selection","operationId":"submit-provider-selection","description":"Submit the provider details selected by the PSU\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformActionProviderSelection"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction"},"example":{"status":"authorizing","authorization_flow":{"actions":{"next":{"type":"scheme_selection","schemes":[{"id":"faster_payments_service","recommended":true}]}}}}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/authorization-flow/actions/scheme-selection":{"post":{"tags":["Payments"],"summary":"Submit scheme selection","operationId":"submit-scheme-selection","description":"Submit the scheme details selected by the PSU\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformActionSchemeSelection"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/authorization-flow/actions/form":{"post":{"tags":["Payments"],"summary":"Submit form","operationId":"submit-form","description":"Submit form details filled by the PSU.\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SubmitForm"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction"},"example":{"status":"authorizing","authorization_flow":{"actions":{"next":{"type":"form","inputs":[{"type":"select","id":"embedded-auth-flow-sca-select","mandatory":true,"display_text":{"key":"embedded-step.embedded-auth-flow-sca-select.display-label","default":"Select SCA method:"},"options":[{"id":"Sms","display_text":{"key":"embedded-auth-flow-sca-select.Sms","default":"SMS"},"search_aliases":["text","mobile","kurznachricht","kurzmitteilung"]},{"id":"PhotoTan","display_text":{"key":"embedded-auth-flow-sca-select.PhotoTan","default":"PhotoTAN"},"search_aliases":["app","code","qr","scan"]}]}]}}}}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}},"502":{"description":"Provider Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsProviderError"}}}}}}},"/v3/payments/{id}/authorization-flow/actions/consent":{"post":{"tags":["Payments"],"summary":"Submit consent","operationId":"submit-consent","description":"Submit the consent given by the user\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SubmitConsent"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction","example":{"status":"authorizing","authorization_flow":{"actions":{"next":{"type":"redirect","uri":"https://pay-mock-connect.truelayer-sandbox.com/login/02ae1d6d-f1fa-4f1e-bd59-966f66ea7407#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwMmFlMWQ2ZC1mMWZhLTRmMWUtYmQ1OS05NjZmNjZlYTc0MDciLCJzY29wZSI6InBheS1tb2NrLWNvbm5lY3QtYXBpIiwibmJmIjoxNjk5MzU4ODQ4LCJleHAiOjE2OTkzNjI0NDgsImlzcyI6Imh0dHBzOi8vcGF5LW1vY2stY29ubmVjdC50cnVlbGF5ZXItc2FuZGJveC5jb20iLCJhdWQiOiJodHRwczovL3BheS1tb2NrLWNvbm5lY3QudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.6T_s1zSZnE2O0iTsln-3hkFK_mfmn3qLCiHyAXSAZPs"}}}}}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/authorization-flow/actions/user-account-selection":{"post":{"tags":["Payments"],"summary":"Submit user account selection","operationId":"submit-user-account-selection","description":"Submit the user account selection option given by the user\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SubmitUserAccountSelection"}}}},"responses":{"200":{"description":"Payment","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformPaymentAction"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/actions/cancel":{"post":{"tags":["Payments"],"summary":"Cancel payment","operationId":"cancel-payment","description":"Cancel a payment \n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to fetch;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"responses":{"202":{"description":"Accepted","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/actions/save-user-account":{"post":{"tags":["Payments"],"summary":"Save payment account","operationId":"save-user-account-payment","description":"Save the account details associated with a payment for subsequent re-use. This endpoint can be called for closed-loop payments.\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to fetch;\n- using a backend bearer token.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"responses":{"202":{"description":"Accepted","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}":{"get":{"tags":["Payments"],"summary":"Get payment","operationId":"get-payment","description":"Returns payment details.\n\nThis API can be called:\n- using the `resource_token` associated with the payment you are trying to fetch;\n- using a backend bearer token.\n\n_**Note:** Some fields are required when OAuth2 token is used._\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]}],"parameters":[{"in":"path","name":"id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"responses":{"200":{"description":"Payment","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetPayment"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments-providers/search":{"post":{"tags":["Payments providers"],"summary":"Search Payments providers","operationId":"search-payment-providers","description":"Returns a list of payments providers.\n","security":[{"OAuth2":["payments"]}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SearchPaymentsProvidersRequest"}}}},"responses":{"200":{"description":"Payment providers","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SearchPaymentsProviders"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments-providers/{id}":{"get":{"tags":["Payments providers"],"summary":"Get payments provider","operationId":"get-payment-provider","description":"Returns payments provider details.\n\nThis API can be called without the need for authentication.\n","security":[{"OAuth2":["payments"]},{"PaymentToken":[]},{"MandateToken":[]}],"parameters":[{"in":"path","name":"id","description":"ID of the payment provider.","schema":{"$ref":"#/components/schemas/ProviderId"},"required":true},{"in":"query","name":"client_id","description":"ID of the client.","schema":{"type":"string"},"required":false},{"in":"query","name":"icon_type","description":"Configuration for the type of icon. Available options are:\n- `default`: Default icon with no background (SVG).\n- `extended`: Extended to a square with an appropriate background colour (SVG).\n- `extended_small`: Extended icon with 192x192 px size (JPEG).\n- `extended_medium`: Extended icon with 432x432 px size (JPEG).\n- `extended_large`: Extended icon jpeg with 864x864 px size (JPEG).\n","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Payment provider","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PaymentsProvider"}}}},"404":{"description":"Provider Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{id}/refunds":{"post":{"tags":["Payments"],"summary":"Create payment refund","operationId":"create-payment-refund","description":"Refund a merchant account payment.\n","security":[{"OAuth2":["payments"]},{"OAuth2":["payments:refund"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"The payment ID for the payment to be fully or partially refunded.","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatePaymentRefund"}}}},"responses":{"202":{"description":"Refund","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PaymentRefundCreated"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment ID Not Found","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}}}},"get":{"tags":["Payments"],"summary":"Get payment refunds","operationId":"get-payment-refunds","description":"Returns all refunds of a payment.","security":[{"OAuth2":["payments"]},{"OAuth2":["payments:refund"]}],"parameters":[{"in":"path","name":"id","description":"ID of the merchant account payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true}],"responses":{"200":{"description":"Refunds of the payment","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetPaymentRefunds"}}}},"401":{"description":"Unauthenticated","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payment ID Not Found","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payments/{payment_id}/refunds/{refund_id}":{"get":{"tags":["Payments"],"summary":"Get payment refund","operationId":"get-payment-refund","description":"Returns refund details.\n","security":[{"OAuth2":["payments"]},{"OAuth2":["payments:refund"]}],"parameters":[{"in":"path","name":"payment_id","description":"ID of the payment","schema":{"$ref":"#/components/schemas/PaymentId"},"required":true},{"in":"path","name":"refund_id","description":"ID of the refund","schema":{"type":"string","description":"Unique ID for the refund","example":"43d12d0f-d775-410f-aaff-482200c17017"},"required":true}],"responses":{"200":{"description":"Refund","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PaymentRefund"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Refund Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payouts":{"post":{"tags":["Payouts"],"summary":"Create payout","operationId":"create-payout","description":"Pay out from one of your merchant accounts.\n","security":[{"OAuth2":["payments"]},{"OAuth2":["payments:payout:business_account"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatePayout"},"examples":{"External account":{"value":{"merchant_account_id":"ae094a73-d874-4241-a65f-6dcda7ac07b1","amount_in_minor":100,"currency":"GBP","beneficiary":{"type":"external_account","reference":"a-reference","account_holder_name":"John Doe","account_identifier":{"type":"sort_code_account_number","sort_code":"123456","account_number":"12345678"}}}},"Verified payouts | Account holder name check":{"value":{"merchant_account_id":"ae094a73-d874-4241-a65f-6dcda7ac07b1","amount_in_minor":100,"currency":"GBP","beneficiary":{"type":"user_determined","reference":"a-reference","user":{"name":"John Doe","email":"john.doe@truelayer.com"},"verification":{"verify_name":true},"provider_selection":{"type":"user_selected","filter":{"countries":["GB"]}}}}},"Verified payouts | Transaction detection with preselected provider":{"value":{"merchant_account_id":"ae094a73-d874-4241-a65f-6dcda7ac07b1","amount_in_minor":100,"currency":"GBP","beneficiary":{"type":"user_determined","reference":"a-reference","user":{"name":"John Doe","phone":"+447700900000"},"verification":{"verify_name":true,"transaction_search_criteria":{"tokens":["18db38","Betropolis LTD","LC Betropolis"],"amount_in_minor":2000,"currency":"GBP","created_at":"2024-05-07"}},"provider_selection":{"type":"preselected","provider_id":"ob-barclays"}}}}}}}},"responses":{"202":{"description":"Payout","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreatePayout-2"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"},"examples":{"missing_token":{"summary":"Missing Token","value":{"type":"https://docs.truelayer.com/docs/payments-api-errors#unauthenticated","title":"Unauthenticated","status":401,"trace_id":"96ce50247f87f540bb2d86771b3728b8","detail":"A Bearer token must be provided in the Authorization header."}},"invalid_scope":{"summary":"Invalid Scope","value":{"type":"https://docs.truelayer.com/docs/payments-api-errors#unauthenticated","title":"Unauthenticated","status":401,"trace_id":"96ce50247f87f540bb2d86771b3728b8","detail":"Authorization: The JWT was not able to be validated: InvalidAudience."}}}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"429":{"description":"Rate Limit Exceeded","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payouts/{id}":{"get":{"tags":["Payouts"],"summary":"Get payout","operationId":"get-payout","description":"Returns payout details.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"in":"path","name":"id","description":"ID of the payout","schema":{"$ref":"#/components/schemas/PayoutId"},"required":true}],"responses":{"200":{"description":"Payout","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Payout Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/payouts/{id}/authorization-flow":{"get":{"tags":["Payouts"],"summary":"Get authorization flow","operationId":"get-payout-authorization-flow","description":"Get the authorization flow for a payout.\n\nThis API can be called using the `resource_token` associated with the payout you are trying to fetch.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"in":"path","name":"id","description":"ID of the payout","schema":{"$ref":"#/components/schemas/PayoutId"},"required":true}],"responses":{"200":{"description":"Perform payout authorization action","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetPayoutAuthorizationFlowResponse"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Authorization flow not found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}},"post":{"tags":["Payouts"],"summary":"Start authorization flow","operationId":"start-payout-authorization-flow","description":"Start the authorization flow for a payout.\n\nThis API can be called using the `resource_token` associated with the payout you are trying to fetch.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/PsuIpAddressHeader","description":"Used to collect and record end-user IP address.\nThe first IP address in the [list](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) will be used as the end-user IP address.\n"},{"$ref":"#/components/parameters/DeviceUserAgentHeader","description":"Used to improve end-user's authentication experience based on device type.\nIf omitted, the `User-Agent` header will be used instead.\n"},{"in":"path","name":"id","description":"ID of the payout","schema":{"$ref":"#/components/schemas/PayoutId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/StartPayoutAuthorizationFlow"}}}},"responses":{"200":{"description":"Perform payout authorization action","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/StartPayoutAuthorizationFlowResponse"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"409":{"description":"Conflict","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/merchant-accounts":{"get":{"tags":["Merchant accounts"],"summary":"List merchant accounts","operationId":"list-operating-accounts","description":"List all your TrueLayer's merchant accounts.\nThere might be more than one account per currency.\n","security":[{"OAuth2":["payments"]}],"responses":{"200":{"description":"Merchant accounts.","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ListMerchantAccounts"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/merchant-accounts/{id}":{"get":{"tags":["Merchant accounts"],"summary":"Get merchant account","operationId":"get-operating-account","description":"Get the details of a single merchant account.\n","parameters":[{"in":"path","name":"id","description":"ID of the merchant account to be returned","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true}],"security":[{"OAuth2":["payments"]}],"responses":{"200":{"description":"Merchant account.","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MerchantAccount"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/merchant-accounts/{id}/transactions":{"get":{"tags":["Merchant accounts"],"summary":"Get transactions","operationId":"merchant-account-get-transactions","description":"Get the transactions of a single merchant account. Transactions are filtered and sorted by settled or executed date.\n> 🚧\n> If the pagination object is missing, add a header `tl-enable-pagination: true` in the request to enable pagination (for more details click [here](https://docs.truelayer.com/docs/get-your-merchant-account-transactions-or-payment-sources#pagination-for-the-transactions-endpoint))\n","parameters":[{"in":"path","name":"id","description":"ID of the merchant account to return the transactions for.","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true},{"in":"query","name":"from","description":"Timestamp for the start of the range to query (inclusive). Uses the ISO-8601 format of YYYY-MM-DDTHH:MM:SS±HHMM.","schema":{"type":"string","format":"datetime"},"required":true},{"in":"query","name":"to","description":"Timestamp for the end of the range to query (exclusive). Uses the ISO-8601 format of YYYY-MM-DDTHH:MM:SS±HHMM.","schema":{"type":"string","format":"datetime"},"required":true},{"in":"query","name":"cursor","description":"Cursor used for pagination purposes, returned as `next_cursor` in the response payload of the inital request. Not required to access the first page of items.","schema":{"type":"string"}},{"in":"query","name":"type","description":"Filters transactions by payments or payouts. If omitted, both payments and payouts are returned.","schema":{"type":"string","enum":["payment","payout"]}}],"security":[{"OAuth2":["payments"]}],"responses":{"200":{"description":"Transactions","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetTransactions"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/merchant-accounts/{id}/sweeping":{"post":{"tags":["Merchant accounts"],"summary":"Set up or update sweeping","operationId":"merchant-account-setup-sweeping","description":"Set the automatic sweeping settings for a merchant account.\n\nAt regular intervals, any available balance in excess of the configured `max_amount_in_minor` is withdrawn to a pre-configured IBAN.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"ID of the merchant account to fetch the settings for","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SweepingSettingsRequested"}}}},"responses":{"204":{"description":"Automatic sweeping enabled","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}},"delete":{"tags":["Merchant accounts"],"summary":"Disable sweeping","operationId":"merchant-account-disable-sweeping","description":"Disable automatic sweeping for a merchant account.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"ID of the merchant account to fetch the settings for","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true}],"responses":{"204":{"description":"Automatic sweeping disabled","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}},"get":{"tags":["Merchant accounts"],"summary":"Get sweeping settings","operationId":"merchant-account-get-sweeping","description":"Get the automatic sweeping settings for a merchant account.\n","security":[{"OAuth2":["payments"]}],"parameters":[{"in":"path","name":"id","description":"ID of the merchant account to fetch the settings for","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true}],"responses":{"200":{"description":"Automatic sweeping settings","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SweepingSettingsConfigured"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found or Automatic sweeping not enabled","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/merchant-accounts/{id}/payment-sources":{"get":{"tags":["Merchant accounts"],"summary":"Get payment sources","operationId":"get-merchant-account-payment-sources","description":"Get the payment sources from which the merchant account has received payment\n","parameters":[{"in":"path","name":"id","description":"ID of the merchant account into which payments were made","schema":{"$ref":"#/components/schemas/MerchantAccountId"},"required":true},{"in":"query","name":"user_id","description":"ID of the user","schema":{"$ref":"#/components/schemas/UserId"},"required":true}],"security":[{"OAuth2":["payments"]}],"responses":{"200":{"description":"User external account payment sources.","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/UserPaymentSources"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Account Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates":{"post":{"tags":["Mandates"],"summary":"Create mandate","operationId":"create-mandate","description":"Create a new mandate\n\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["mandates"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreateMandate"}}}},"responses":{"201":{"description":"Mandate Created","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MandateCreated"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsRateLimitExceeded"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}},"get":{"tags":["Mandates"],"summary":"List mandates","operationId":"list-mandate","description":"List all the mandates associated to the client used.\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["mandates"]}],"parameters":[{"in":"query","name":"user_id","description":"ID of the user","schema":{"$ref":"#/components/schemas/UserId"},"required":false},{"in":"query","name":"cursor","schema":{"$ref":"#/components/schemas/Cursor"},"required":false},{"in":"query","name":"limit","schema":{"$ref":"#/components/schemas/Limit"},"required":false}],"responses":{"200":{"description":"Mandates list","content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ListMandates"}}}},"400":{"description":"Invalid Parameters","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"500":{"description":"Unknown Error","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates/{id}":{"get":{"tags":["Mandates"],"summary":"Get mandate","operationId":"get-mandate","description":"Returns a mandate with the stated ID.\n\nThis endpoint can be called either by the regular `backend token` or the `mandate token` for that mandate.\n","security":[{"OAuth2":["mandates"]},{"MandateToken":[]}],"parameters":[{"in":"path","name":"id","description":"ID of the Mandate","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Mandate","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetMandate"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates/{id}/authorization-flow":{"post":{"tags":["Mandates"],"summary":"Start authorization flow","operationId":"start-mandate-authorization-flow","description":"Start the authorization flow for a mandate.\n\nThis API can be called:\n- using the `mandate_token` associated with the Mandate you are trying to fetch; or\n- using a backend bearer token.\n","security":[{"OAuth2":["mandates"]},{"MandateToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the Mandate","schema":{"$ref":"#/components/schemas/MandateId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/StartMandateAuthorizationFlow"}}}},"responses":{"200":{"description":"Mandate Authorization Flow","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/StartMandateAuthorizationFlowResponse"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates/{id}/authorization-flow/actions/consent":{"post":{"tags":["Mandates"],"summary":"Submit consent","operationId":"submit-consent-mandate","description":"Submit the consent given by the user\n\nThis API can be called:\n- using the `mandate_token` associated with the mandate you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["mandates"]},{"PaymentToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the mandate","schema":{"$ref":"#/components/schemas/MandateId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SubmitConsent"}}}},"responses":{"200":{"description":"Mandate Provider Selection Action","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MandateProviderSelectionAction"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}},"502":{"description":"Provider Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsProviderError"}}}}}}},"/v3/mandates/{id}/authorization-flow/actions/provider-selection":{"post":{"tags":["Mandates"],"summary":"Submit provider selection","operationId":"submit-mandate-provider-selection","description":"Submit the provider details selected by the PSU\n\nThis API can be called:\n- using the `mandate_token` associated with the mandate you are trying to authorize;\n- using a backend bearer token.\n","security":[{"OAuth2":["mandates"]},{"MandateToken":[]}],"parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeaderConditional"},{"in":"path","name":"id","description":"ID of the Mandate","schema":{"$ref":"#/components/schemas/MandateId"},"required":true}],"requestBody":{"required":true,"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/PerformActionProviderSelection"}}}},"responses":{"200":{"description":"Mandate Provider Selection Action","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MandateProviderSelectionAction"},"example":{"status":"authorizing","authorization_flow":{"actions":{"next":{"type":"redirect","uri":"https://api.sandbox.natwest.com/authorize?client_id=6vVMdYbg3YzblC5SVaGLW2gjEw4yrCvMti4GoBxjt4w%3D&request=eyJhbGciOiJQUzI1NiIsImtpZCI6Ing2UU1xbjJ6V1BaRFRLWUtWNEJiTXhQQjBhayJ9.eyJhdWQiOiJodHRwczovL2FwaS5zYW5kYm94Lm5hdHdlc3QuY29tIiwibmJmIjoxNjk5ODY4NjM2LCJpc3MiOiI2dlZNZFliZzNZemJsQzVTVmFHTFcyZ2pFdzR5ckN2TXRpNEdvQnhqdDR3PSIsImV4cCI6MTY5OTg2OTI2NiwicmVzcG9uc2VfdHlwZSI6ImNvZGUgaWRfdG9rZW4iLCJjbGllbnRfaWQiOiI2dlZNZFliZzNZemJsQzVTVmFHTFcyZ2pFdzR5ckN2TXRpNEdvQnhqdDR3PSIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vcGF5LnRydWVsYXllci1zYW5kYm94LmNvbS9wcm92aWRlci1yZXR1cm4iLCJzY29wZSI6Im9wZW5pZCBwYXltZW50cyIsInN0YXRlIjoibWFuZGF0ZS00YzIyOTFmMzlmYzA0NThhYjdlYTVjNTI1OGYwMzEzZiIsIm5vbmNlIjoiODE1NTM1NWUtNTRiNC00YjRmLWEyOWEtN2NhZTgxOTI3OWE2IiwibWF4X2FnZSI6ODY0MDAsImNsYWltcyI6eyJ1c2VyaW5mbyI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJWUlAtMDA5OTQ5ZDktZDA2My00Yzc0LWI5NGUtZjM3MzIzYTQ5ZTBiIiwiZXNzZW50aWFsIjp0cnVlfX0sImlkX3Rva2VuIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6IlZSUC0wMDk5NDlkOS1kMDYzLTRjNzQtYjk0ZS1mMzczMjNhNDllMGIiLCJlc3NlbnRpYWwiOnRydWV9LCJhY3IiOnsiZXNzZW50aWFsIjp0cnVlLCJ2YWx1ZXMiOlsidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwidXJuOm9wZW5iYW5raW5nOnBzZDI6Y2EiXX19fSwiYWNyX3ZhbHVlcyI6InVybjpvcGVuYmFua2luZzpwc2QyOnNjYSB1cm46b3BlbmJhbmtpbmc6cHNkMjpjYSIsImp0aSI6IjliYjFmNDYzLWYifQ.XZTfzRa9sW4Hsbx57GXslLzmaMRHa6RGs_MuNqZiGHtX2_xrfnuO2jftJDfqygMWonqYHY4l3cH3vlERZJNvMHW91ioaro2F8uXTiRoKBN7wnW7YDjfEFZBdLOnS7IvzSDumxAfW0hotuz5gsbKcimF8Um7wNBAKI5V_tvb_Lzi_0FSjUpYzbplOy_nmej6t16pyw0cYwlhuUGQ7VELh7nw2Z8SNp5mA8D-LLS2RNKXwjOczn5CV5P2Q5lN0LQ3VAgy7sCTg70MZQ7Kr8pmKDKqBXwmnuZq-GHgGetY0vgu6e1kydXFygJDjPSJljvtSMpvxYqKgoc45eV2m2c8M4A&state=mandate-4c2291f39fc0458ab7ea5c5258f0313f&nonce=8155355e-54b4-4b4f-a29a-7cae819279a6&scope=openid%20payments&response_type=code%20id_token&redirect_uri=https%3A%2F%2Fpay.truelayer-sandbox.com%2Fprovider-return"}}}}}}},"400":{"description":"Invalid Request","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"},{"$ref":"#/components/schemas/ProblemDetailsConcurrencyConflict"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict","https://docs.truelayer.com/docs/error-types#concurrency-conflict":"#/components/schemas/ProblemDetailsConcurrencyConflict"}}}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}},"502":{"description":"Provider Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsProviderError"}}}}}}},"/v3/mandates/{id}/revoke":{"post":{"tags":["Mandates"],"summary":"Revoke mandate","operationId":"revoke-mandate","description":"Revoke a mandate\n\nThis API must be called using a backend bearer token.\n","security":[{"OAuth2":["mandates"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"in":"path","name":"id","description":"ID of the Mandate","schema":{"type":"string"},"required":true}],"responses":{"204":{"description":"Revocation Successful","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}}},"400":{"description":"BadRequest","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates/{id}/funds":{"get":{"tags":["Mandates"],"summary":"Confirm funds","operationId":"confirm-mandate-funds","description":"Confirm that the PSU has the given funds. \n\nThis API can be called:\n  - using the `mandate_token` associated with the mandate;\n  - using a backend bearer token.\n","security":[{"OAuth2":["mandates"]}],"parameters":[{"in":"path","name":"id","description":"ID of the Mandate","schema":{"$ref":"#/components/schemas/MandateId"},"required":true},{"in":"query","name":"amount_in_minor","required":true,"description":"A 'cent' value representing the amount. eg 100 == 1GBP.","schema":{"type":"integer","minimum":1}},{"in":"query","name":"currency","required":true,"schema":{"$ref":"#/components/schemas/CurrencyCode"}}],"responses":{"200":{"description":"Confirmation of funds","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ConfirmationOfFunds"}}}},"400":{"description":"Invalid Request","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"$ref":"#/components/schemas/ProblemDetailsInvalidState"}],"discriminator":{"propertyName":"type","mapping":{"https://docs.truelayer.com/docs/error-types#invalid-parameters":"#/components/schemas/ProblemDetailsInvalidParameters","https://docs.truelayer.com/docs/error-types#invalid-state":"#/components/schemas/ProblemDetailsInvalidState"}}}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}}}}},"/v3/mandates/{id}/constraints":{"get":{"tags":["Mandates"],"summary":"Get mandate constraints","operationId":"get-constraints","description":"Retrieve the constriants defined on the mandate, as well as\nthe current utilisation of those constraints within the periods.\n","security":[{"OAuth2":["mandates"]}],"parameters":[{"in":"path","name":"id","description":"ID of the Mandate","schema":{"$ref":"#/components/schemas/MandateId"},"required":true}],"responses":{"200":{"description":"Constraints State","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/GetConstraints"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"}}}},"401":{"description":"Unauthenticated","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnauthenticated"}}}},"403":{"description":"Forbidden","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsForbidden"}}}},"404":{"description":"Mandate Not Found","headers":{"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}}}}},"/v3/payments-provider-return":{"post":{"tags":["General"],"summary":"Submit payments return parameters","operationId":"submit-payments-provider-return-parameters","description":"Submit direct return query and fragment parameters returned from the provider.\n","parameters":[{"$ref":"#/components/parameters/OptionalIdempotencyKeyHeaderNoAuth"}],"requestBody":{"description":"Either `query` or `fragment` need to be present.","required":true,"content":{"application/json; charset=UTF-8":{"schema":{"type":"object","title":"Submit provider return parameters for direct Return","properties":{"query":{"type":"string","description":"Submit the query parameters attached to the GET request received by\nthe third-party when redirected back to your `redirect.direct_return_uri`\nset in the start authorization flow action.\n","example":"key1=val1&key2=val2"},"fragment":{"type":"string","description":"Submit the fragment parameters attached to the GET request received by\nthe third-party when redirected back to the `redirect.direct_return_uri`\nset in the start authorization flow action.\n","example":"key1=val1&key2=val2"}}}}}},"responses":{"200":{"description":"Resource","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProviderReturnParametersResponse"}}}},"400":{"description":"Invalid Parameters","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetailsInvalidParameters"},{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/ProviderReturnParametersResource"}}}]}}}},"404":{"description":"Resource Not Found","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsNotFound"}}}},"409":{"description":"Idempotency-Key Concurrency Conflict","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyConcurrencyConflict"}}}},"422":{"description":"Idempotency-Key Reuse","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsIdempotencyKeyReuse"}}}},"500":{"description":"Unknown Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ProblemDetailsUnknownError"}}}},"502":{"description":"Provider Error","headers":{"Tl-Should-Retry":{"$ref":"#/components/headers/Tl-Should-Retry"},"Tl-Trace-Id":{"$ref":"#/components/headers/Tl-Trace-Id"}},"content":{"application/problem+json; charset=UTF-8":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetailsProviderError"},{"type":"object","properties":{"resource":{"$ref":"#/components/schemas/ProviderReturnParametersResource"}}}]}}}}},"security":[]}}},"webhooks":{"payment_links":{"post":{"tags":["Payment links"],"summary":"Payment link webhooks","operationId":"webhook-payment-links","description":"Sent to the webhook URI you registered in Console when a payment is created from a payment link and when a payment link expires.","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookPaymentLinkPaymentCreated"},{"$ref":"#/components/schemas/WebhookPaymentLinkDisabled"}],"discriminator":{"propertyName":"type","mapping":{"payment_link_payment_created":"#/components/schemas/WebhookPaymentLinkPaymentCreated","payment_link_disabled":"#/components/schemas/WebhookPaymentLinkDisabled"}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}},"payments":{"post":{"tags":["Payments"],"summary":"Payment webhooks","operationId":"webhook-payments","description":"Sent to the webhook URI you registered in Console when:\n- a payment is authorised.\n- a payment is executed.\n- a payment fails.\n- a payment settles.\n- a payment is creditable, according to criteria you specified.\n- a payment that has been executed has not settled within a duration you specified.\n- an indemnity claim is made against a payment.\n- a payment is reversed.\n- a Direct Debit payment arrived in the merchant account. The payment can still be reversed at this stage. Contact your ISM or CSM to know more.\n","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookPaymentAuthorized"},{"$ref":"#/components/schemas/WebhookPaymentExecuted"},{"$ref":"#/components/schemas/WebhookPaymentFailed"},{"$ref":"#/components/schemas/WebhookPaymentSettled"},{"$ref":"#/components/schemas/WebhookPaymentCreditable"},{"$ref":"#/components/schemas/WebhookPaymentSettlementStalled"},{"$ref":"#/components/schemas/WebhookPaymentDisputed"},{"$ref":"#/components/schemas/WebhookPaymentReversed"},{"$ref":"#/components/schemas/WebhookPaymentFundsReceived"}],"discriminator":{"propertyName":"type","mapping":{"payment_authorized":"#/components/schemas/WebhookPaymentAuthorized","payment_executed":"#/components/schemas/WebhookPaymentExecuted","payment_failed":"#/components/schemas/WebhookPaymentFailed","payment_settled":"#/components/schemas/WebhookPaymentSettled","payment_creditable":"#/components/schemas/WebhookPaymentCreditable","payment_settlement_stalled":"#/components/schemas/WebhookPaymentSettlementStalled","payment_disputed":"#/components/schemas/WebhookPaymentDisputed","payment_reversed":"#/components/schemas/WebhookPaymentReversed","payment_funds_received":"#/components/schemas/WebhookPaymentFundsReceived"}}},"examples":{"payment_authorized_example_1":{"summary":"Example of a payment_authorized webhook","value":{"type":"payment_authorized","event_version":1,"event_id":"c1e475a8-f838-4a35-95df-51465d66a61d","payment_id":"ecad2b93-efe9-4f25-b82d-920248a9c1ad","payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"payment_source":{"account_identifiers":[{"type":"sort_code_account_number","sort_code":"010101","account_number":"00000011"}],"account_holder_name":"JOHN SANDBRIDGE"},"authorized_at":"2023-06-27T09:54:55.777Z"}},"payment_executed_example_gb":{"summary":"Example of a payment_executed webhook in the UK","value":{"type":"payment_executed","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","executed_at":"2021-12-25T15:00:00.000Z","payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"payment_source":{"account_identifiers":[{"type":"sort_code_account_number","sort_code":"010101","account_number":"00000001"}],"account_holder_name":"JOHN SANDBRIDGE"}}},"payment_executed_example_de":{"summary":"Example of a payment_executed webhook in DE","value":{"type":"payment_executed","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","executed_at":"2021-12-25T15:00:00.000Z","payment_method":{"type":"bank_transfer","provider_id":"mock-payments-de-redirect","scheme_id":"sepa_credit_transfer"},"settlement_risk":{"category":"low_risk"}}},"payment_failed_example":{"summary":"Example of a payment_failed webhook","value":{"type":"payment_failed","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","failed_at":"2021-12-25T15:00:00.000Z","failure_stage":"authorizing","failure_reason":"provider_rejected","payment_method":{"type":"mandate","mandate_id":"d65f3521-fa55-44fc-9a75-ba43456de7f2"},"payment_source":{"account_holder_name":"HOLDER NAME","account_identifiers":[{"type":"sort_code_account_number","sort_code":"111111","account_number":"00000111"}]}}},"payment_settled_example":{"summary":"Example of a payment_settled webhook","value":{"type":"payment_settled","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","payment_method":{"type":"bank_transfer","provider_id":"mock-payments-de-redirect","scheme_id":"sepa_credit_transfer"},"settled_at":"2021-12-25T15:00:00.000Z","payment_source":{"account_identifiers":[{"type":"iban","iban":"DE89370400440532013000"}],"id":"1f111d3c-9427-43be-1111-1111219d111c","account_holder_name":"HOLDER NAME"},"user_id":"ec01ece1-1dbe-48f1-82b2-bce8cfa44d08"}},"payment_settlement_stalled_example":{"summary":"Example of a payment_settlement_stalled webhook","value":{"type":"payment_settlement_stalled","event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","event_version":1,"payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","settlement_stalled_at":"2023-06-13T15:00:00.000Z"}},"payment_reversed_example":{"summary":"Example of a payment_reversed webhook","value":{"type":"payment_reversed","event_version":1,"event_id":"744b2fbe-9000-4eca-be1c-eee11120a096","payment_id":"039f4e28-8f5b-4d81-8089-61a90df61214","reversal_reason":"corrected","metadata":{"WMbReElDgIrPY2XL2rx0rlvvenuQU8bSIwwiTeMHlIHsWT6rksA1IuB2nTeBtEgatynHoBFVlmf3gWvHnXZNxm8NH7NWUk4rz4D4FPYydT3peeOwyXgYE2xvH7VK9EZpCVpS8Cy2KRGtJQYNWAq9":"mjssd94QlFTtN7NGxwHQ","GkyDLvZ03F51P5uzX7q6qFcdcYz5Bd9xEQuc2vesynZNMkyasfBwCcsZ5RukUSqsZJn3pdoHp3R4p7uVnPTXa6LpTmSOB9cPjeeFzqSaI32XI17RtQxrmP3lqYRS7rAbLQJTwCeVoIPgNPOnOQp9vTfuyaeJil0MhZc7dOOkRMp0wwaNUP4wmjNHTRlSTUQu8lWtyP2p6wkoJ8nEUPfNTEMqVFuugmeNE8EbcimXqokQVxR9dtxlzzvzjJPrhYeA40Kkm0JbScCYuhlVmoLPooVXhL3LoKuYweufm4wo3":"XfPDALsbPk45mzElYJDJVnqt"},"reversed_at":"2025-04-04T12:20:10.448Z"}},"payment_creditable_example":{"summary":"Example of a payment_creditable webhook","value":{"type":"payment_creditable","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","payment_id":"60c0a60ed8d7-4e5b-ac79-401b1d8a8633","creditable_at":"2023-06-13T15:00:00.000Z"}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}},"refunds":{"post":{"tags":["Payments"],"summary":"Refund webhooks","x-readme":{"code-samples":[{"language":"json","name":"refund_executed Example","correspondingExample":"refund_executed"},{"language":"json","name":"refund_failed Example","correspondingExample":"refund_failed"}]},"operationId":"webhook-refunds","description":"Sent to the webhook URI you registered in Console when a refund succeeds or fails.","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookRefundExecuted"},{"$ref":"#/components/schemas/WebhookRefundFailed"}],"discriminator":{"propertyName":"type","mapping":{"refund_executed":"#/components/schemas/WebhookRefundExecuted","refund_failed":"#/components/schemas/WebhookRefundFailed"}}},"examples":{"refund_executed":{"summary":"Refund Executed","value":{"type":"refund_executed","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","refund_id":"43d12d0f-d775-410f-aaff-482200c17017","payment_id":"0afd1f6a-f611-48ce-9488-321129bb3a70","executed_at":"2021-12-25T15:00:00.000Z","scheme_id":"faster_payments_service","metadata":{"prop1":"value1","prop2":"value2"}}},"refund_failed":{"summary":"Refund Failed","value":{"type":"refund_failed","event_version":1,"event_id":"c9e5eeb1-aa3d-5e88-b7eb-5726f5e5c052","refund_id":"54e23e1a-a886-521a-bbaa-593311cc4b81","payment_id":"1bae2a7b-a722-59dd-a599-432240dd4b81","failed_at":"2021-12-25T15:30:00.000Z","failure_reason":"insufficient_funds","metadata":{"prop1":"value1","prop2":"value2"}}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}},"payouts":{"post":{"tags":["Payouts"],"summary":"Payout webhooks","operationId":"webhook-payouts","description":"Sent to the webhook URI you registered in Console when a payout succeeds or fails.","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookPayoutExecuted"},{"$ref":"#/components/schemas/WebhookPayoutFailed"}],"discriminator":{"propertyName":"type","mapping":{"payout_executed":"#/components/schemas/WebhookPayoutExecuted","payout_failed":"#/components/schemas/WebhookPayoutFailed"}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}},"mandates":{"post":{"tags":["Mandates"],"summary":"Mandate webhooks","operationId":"webhook-mandates","description":"Sent to the webhook URI you registered in Console when a mandate becomes authorized, fails, or is revoked.","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookMandateAuthorized"},{"$ref":"#/components/schemas/WebhookMandateFailed"},{"$ref":"#/components/schemas/WebhookMandateRevoked"},{"$ref":"#/components/schemas/WebhookMandateRemitterChanged"},{"$ref":"#/components/schemas/WebhookMandateInitialPaymentCreated"}],"discriminator":{"propertyName":"type","mapping":{"mandate_authorized":"#/components/schemas/WebhookMandateAuthorized","mandate_failed":"#/components/schemas/WebhookMandateFailed","mandate_revoked":"#/components/schemas/WebhookMandateRevoked","mandate_remitter_changed":"#/components/schemas/WebhookMandateRemitterChanged","mandate_initial_payment_created":"#/components/schemas/WebhookMandateInitialPaymentCreated"}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}},"merchant_accounts":{"post":{"tags":["Merchant accounts"],"summary":"Merchant account webhooks","operationId":"webhook-merchant-accounts","description":"Sent to the webhook URI you registered in Console when you receive a payment not initiated through TrueLayer to your merchant account.","parameters":[{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookExternalPaymentReceived"},{"$ref":"#/components/schemas/WebhookBalanceNotification"}],"discriminator":{"propertyName":"type","mapping":{"external_payment_received":"#/components/schemas/WebhookExternalPaymentReceived","balance_notification":"#/components/schemas/WebhookBalanceNotification"}}}}}},"responses":{"200":{"description":"Webhook Handled"}},"security":[]}}},"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://auth.truelayer.com/connect/token","scopes":{"payments":"for accessing all the endpoints of Payments API v3"}}}},"PaymentToken":{"type":"http","scheme":"bearer","description":"A secret returned from one of our create endpoints for use with our authorization endpoints.\nScoped to a single resource.\n"},"MandateToken":{"type":"http","scheme":"bearer","description":"A secret returned from the create mandate endpoint for use with our authorization endpoints.\nScoped to a single mandate.\n"}},"parameters":{"IdempotencyKeyHeader":{"in":"header","required":true,"name":"Idempotency-Key","description":"An idempotency key to allow safe retrying without the operation being performed multiple times.\nThe value should be unique for each operation, e.g. a UUID, with the same key being sent on a retry of the same request.\n","schema":{"type":"string"}},"SignatureHeader":{"in":"header","name":"Tl-Signature","description":"A JWS with detached content, signed with your private key.\nSee [Request Signing](https://docs.truelayer.com/docs/sign-your-requests)\n","schema":{"type":"string"},"required":true},"PsuIpAddressHeader":{"in":"header","name":"X-Forwarded-For","description":"Used to collect and record end-user IP address.\nThe first IP address in the [list](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) will be used as the end-user IP address.\n","schema":{"type":"string"},"required":false},"DeviceUserAgentHeader":{"in":"header","name":"X-Device-User-Agent","description":"Used to improve end-user's authentication experience based on device type.\nIf omitted, the `User-Agent` header will be used instead.\n","schema":{"type":"string"},"required":false},"OptionalIdempotencyKeyHeader":{"in":"header","name":"Idempotency-Key","description":"An idempotency key to allow safe retrying without the operation being performed multiple times.\nThe value should be unique for each operation (we strongly advise to use a UUID v4), with the same key being sent on a retry of the same request.\n","schema":{"type":"string"}},"SignatureHeaderConditional":{"in":"header","name":"Tl-Signature","description":"A JWS with detached content, signed with your private key.\nSee [Request Signing](https://docs.truelayer.com/docs/sign-your-requests).\n\nRequired with a OAuth2 token.\n","schema":{"type":"string"}},"OptionalIdempotencyKeyHeaderNoAuth":{"in":"header","name":"Idempotency-Key","description":"An idempotency key to allow safe retrying without the operation being performed multiple times.\nThe value should be unique for each operation (we strongly advise to use a UUID v4), with the same key being sent on a retry of the same request.\nIf a UUID can't be used, we advise to also include your client id in the idempotency key.\n","schema":{"type":"string"}},"WebhookSignatureHeader":{"in":"header","name":"Tl-Signature","description":"A JWS with detached content, verifiable with our public key.\nSee [Webhook Request Signing](/docs/configure-webhooks-for-your-integration#validate-the-signature-of-received-webhooks)\n","schema":{"type":"string"},"required":true}},"schemas":{"CurrencyCode":{"type":"string","enum":["GBP","EUR"],"example":"GBP"},"CountryCode":{"type":"string","enum":["AT","BE","DE","DK","ES","FI","FR","GB","IE","IT","LT","NL","NO","PL","PT","RO"]},"ProviderFilter":{"title":"Provider Filter","type":"object","description":"Configuration options to constrain which providers should be available\nduring the `provider_selection` action.\n","properties":{"countries":{"type":"array","description":"Only providers from the specified countries will be returned.","items":{"$ref":"#/components/schemas/CountryCode"},"uniqueItems":true,"minItems":1,"example":["GB"]},"release_channel":{"type":"string","description":"The lowest stability release stage of a provider that should be returned.\n\nNote that many EUR providers are in `public_beta` or `private_beta`.\n","default":"general_availability","enum":["general_availability","public_beta","private_beta"],"example":"general_availability"},"customer_segments":{"type":"array","description":"The customer segments that providers cater to that should be returned. By default, returns retail only.","default":["retail"],"items":{"type":"string","enum":["retail","business","corporate"]},"uniqueItems":true,"minItems":1,"example":["retail"]},"provider_ids":{"type":"array","description":"IDs of providers to include in those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["mock-payments-gb-redirect"]},"excludes":{"type":"object","description":"Options to exclude providers included by the filters","properties":{"provider_ids":{"type":"array","description":"IDs of providers to explicitly exclude from those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["ob-exclude-this-bank"]}}}}},"SchemeSelectionInstantOnly":{"title":"Instant only","type":"object","description":"Only allow providers that support instant payments.","required":["type"],"properties":{"type":{"type":"string","description":"The type of scheme selection.\nOnly allow providers that support instant payments.\n","enum":["instant_only"]},"allow_remitter_fee":{"type":"boolean","description":"Whether to allow providers that might charge the remitter a transaction fee. If `false`, only providers supporting schemes that are free will be available to select in the provider selection action.\nUnless explicitly set, will default to `false`.\n","default":false},"instant_override_provider_ids":{"type":"array","description":"An array of provider ids. If the user selects one of the providers specified in this list, the payment always goes through an instant scheme. This ignores any settings you specify for allow_remitter_fee.\n","items":{"type":"string"}},"non_instant_override_provider_ids":{"type":"array","description":"An array of provider ids. If the user selects one of the providers specified in this list, the payment always goes through a non instant scheme. This ignores any settings you specify for allow_remitter_fee.\n","items":{"type":"string"}}}},"SchemeSelectionInstantPreferred":{"title":"Instant preferred","type":"object","description":"Prefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable.\n","required":["type"],"properties":{"type":{"type":"string","description":"The type of scheme selection.\nPrefer providers that allow instant payments, but allow defaulting back to non-instant payments if unavailable.\n","enum":["instant_preferred"]},"allow_remitter_fee":{"type":"boolean","description":"Whether to allow providers that might charge the remitter a transaction fee. If `false`, only providers supporting schemes that are free will be available to select in the provider selection action.\nUnless explicitly set, will default to `false`.\n","default":false},"instant_override_provider_ids":{"type":"array","description":"An array of provider ids. If the user selects one of the providers specified in this list, the payment always goes through an instant scheme. This ignores any settings you specify for allow_remitter_fee.\n","items":{"type":"string"}},"non_instant_override_provider_ids":{"type":"array","description":"An array of provider ids. If the user selects one of the providers specified in this list, the payment always goes through a non instant scheme. This ignores any settings you specify for allow_remitter_fee.\n","items":{"type":"string"}}}},"SchemeSelectionUserSelected":{"title":"User selected","type":"object","description":"Indicates that the scheme is to be selected from a collection.\nNote: This scheme selection method is only supported by some versions of TrueLayer's mobile SDKs. Only use this option when you're sure that the end user has a version of your app on their device that supports scheme selection, or they won't be able to complete the payment. If you integrate with TrueLayer APIs directly, you must show the user a UI for scheme selection.\n","required":["type"],"properties":{"type":{"type":"string","description":"The type of scheme selection.","enum":["user_selected"]}}},"ProviderSelectionUserSelectedSchemeSelection":{"title":"Scheme Selection","type":"object","description":"Scheme Selection","oneOf":[{"$ref":"#/components/schemas/SchemeSelectionInstantOnly"},{"$ref":"#/components/schemas/SchemeSelectionInstantPreferred"},{"$ref":"#/components/schemas/SchemeSelectionUserSelected"}],"discriminator":{"propertyName":"type","mapping":{"instant_only":"#/components/schemas/SchemeSelectionInstantOnly","instant_preferred":"#/components/schemas/SchemeSelectionInstantPreferred","user_selected":"#/components/schemas/SchemeSelectionUserSelected"}}},"ProviderSelectionUserSelectedRemitter":{"title":"Remitter account details","type":"object","description":"Remitter","required":["account_holder_name"],"properties":{"account_holder_name":{"description":"The name of the external account holder. This field will be required if the selected provider requires it, otherwise it will be optional.\npattern: `^[^\\(\\)]{1,80}$`\n","type":"string","example":"Mike Smith","maxLength":80,"pattern":"^[^\\(\\)]{1,80}$"}}},"ProviderSelectionUserSelected":{"title":"User selected","type":"object","description":"Indicates that the provider is to be selected from a collection","required":["type"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["user_selected"]},"filter":{"$ref":"#/components/schemas/ProviderFilter"},"scheme_selection":{"$ref":"#/components/schemas/ProviderSelectionUserSelectedSchemeSelection"},"remitter":{"$ref":"#/components/schemas/ProviderSelectionUserSelectedRemitter"}}},"AccountIdentifierScan":{"type":"object","title":"Sort Code + Account Number","description":"The scheme identifier for a bank account participating in UK payment schemes.","required":["type","sort_code","account_number"],"properties":{"type":{"description":"The type of scheme identifier.","type":"string","enum":["sort_code_account_number"]},"sort_code":{"description":"6 digit sort code (no spaces or dashes). pattern: `^[0-9]{6}$`","type":"string","minLength":6,"maxLength":6,"example":"560029","pattern":"^[0-9]{6}$"},"account_number":{"description":"8 digit account number. pattern: `^[0-9]{8}$`","type":"string","minLength":8,"maxLength":8,"example":"26207729","pattern":"^[0-9]{8}$"}}},"AccountIdentifierIban":{"type":"object","title":"IBAN","description":"The international bank account number.","required":["type","iban"],"properties":{"type":{"description":"The type of scheme identifier.","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). pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$`","type":"string","minLength":15,"maxLength":34,"example":"GB32CLRB04066800012315","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$"}}},"AccountIdentifierBban":{"type":"object","title":"BBAN","description":"Basic bank account number.\n","required":["type","bban"],"properties":{"type":{"description":"The type of scheme identifier.","type":"string","enum":["bban"]},"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"}}},"AccountIdentifierNrb":{"type":"object","title":"NRB","description":"The scheme identifier for a bank account participating in Poland's payment schemes.\n","required":["type","nrb"],"properties":{"type":{"description":"The type of scheme identifier.","type":"string","enum":["nrb"]},"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"}}},"PaymentAccountIdentifier":{"title":"Account Identifier","oneOf":[{"$ref":"#/components/schemas/AccountIdentifierScan"},{"$ref":"#/components/schemas/AccountIdentifierIban"},{"$ref":"#/components/schemas/AccountIdentifierBban"},{"$ref":"#/components/schemas/AccountIdentifierNrb"}],"discriminator":{"propertyName":"type","mapping":{"sort_code_account_number":"#/components/schemas/AccountIdentifierScan","iban":"#/components/schemas/AccountIdentifierIban","bban":"#/components/schemas/AccountIdentifierBban","nrb":"#/components/schemas/AccountIdentifierNrb"}},"description":"A unique account identifier for an external account."},"Remitter":{"title":"Remitter account details","type":"object","description":"Remitter","required":["account_holder_name","account_identifier"],"properties":{"account_holder_name":{"description":"The name of the external account holder. \npattern: `^[^\\(\\)]{1,80}$`\n","type":"string","example":"Mike Smith","maxLength":80,"pattern":"^[^\\(\\)]{1,80}$"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"}}},"PaymentLinkProviderSelectionPreselected":{"title":"Preselected","type":"object","description":"Preselected provider. Indicates that the provider for this payment is preselected.","required":["type","provider_id","scheme_id"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["preselected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment.","example":"eg-provider"},"scheme_id":{"type":"string","description":"The id of the scheme to make the payment over.","example":"faster_payments_service"},"remitter":{"$ref":"#/components/schemas/Remitter"}}},"PaymentLinkBankTransferProviderSelection":{"title":"Provider Selection","type":"object","description":"Provider Selection","oneOf":[{"$ref":"#/components/schemas/ProviderSelectionUserSelected"},{"$ref":"#/components/schemas/PaymentLinkProviderSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"user_selected":"#/components/schemas/ProviderSelectionUserSelected","preselected":"#/components/schemas/PaymentLinkProviderSelectionPreselected"}}},"MerchantAccountId":{"type":"string","description":"Unique ID for the Merchant Account","format":"uuid","example":"AB8FA060-3F1B-4AE8-9692-4AA3131020D0"},"AutomatedVerification":{"type":"object","title":"automated","description":"In an automated verification, Truelayer will perform additional checks on the remitter. You can only perform additional checks for one of name or date of birth, not both.","required":["type"],"properties":{"type":{"description":"The type of verification.","type":"string","enum":["automated"]},"remitter_name":{"description":"Enable verification for the remitter name.","type":"boolean"},"remitter_date_of_birth":{"description":"Enable verification for the remitter date of birth.","type":"boolean"}}},"Verification":{"oneOf":[{"$ref":"#/components/schemas/AutomatedVerification"}],"discriminator":{"propertyName":"type","mapping":{"automated":"#/components/schemas/AutomatedVerification"}}},"PaymentDestinationMerchantAccount":{"type":"object","title":"Merchant Account","description":"The identifier for a TrueLayer merchant account.","required":["type","merchant_account_id"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["merchant_account"]},"merchant_account_id":{"description":"The unique identifier of a TrueLayer merchant account.","$ref":"#/components/schemas/MerchantAccountId"},"account_holder_name":{"description":"The name of the beneficiary, which displays in the remitter's bank statement.\nIf unspecified, the API uses the account owner name associated with the selected merchant account.\npattern: `^[^\\(\\)]+$`\n","type":"string","example":"Ben Eficiary","maxLength":40,"pattern":"^[^\\(\\)]+$"},"reference":{"description":"A reference for the payment. Not visible to the remitter.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$`\n","type":"string","maxLength":100,"example":"payment-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$"},"verification":{"description":"The verification of the remitter info. If specified, the API performs additional checks on the remitter information.\n","$ref":"#/components/schemas/Verification"},"statement_reference":{"description":"Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$`\n","type":"string","maxLength":18,"example":"payment-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$"}}},"PaymentDestinationExternalAccount":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","account_identifier","reference"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["external_account"]},"account_holder_name":{"description":"The name of the external account holder. Note that some providers have an 18-character upper limit for this.\npattern: `^[^\\(\\)]+$`\n","type":"string","maxLength":40,"example":"Ben Eficiary","pattern":"^[^\\(\\)]+$"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"},"reference":{"description":"A reference for the payment.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$`\n","type":"string","maxLength":18,"example":"payment-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$"}}},"PaymentDestination":{"oneOf":[{"$ref":"#/components/schemas/PaymentDestinationMerchantAccount"},{"$ref":"#/components/schemas/PaymentDestinationExternalAccount"}],"discriminator":{"propertyName":"type","mapping":{"merchant_account":"#/components/schemas/PaymentDestinationMerchantAccount","external_account":"#/components/schemas/PaymentDestinationExternalAccount"}}},"PaymentLinkPaymentMethodBankTransfer":{"title":"Bank Transfer","type":"object","required":["type","provider_selection","beneficiary"],"properties":{"type":{"type":"string","description":"The type of payment method.","enum":["bank_transfer"]},"provider_selection":{"$ref":"#/components/schemas/PaymentLinkBankTransferProviderSelection"},"beneficiary":{"$ref":"#/components/schemas/PaymentDestination"}}},"PaymentLinkMethod":{"title":"Payment Method","type":"object","oneOf":[{"$ref":"#/components/schemas/PaymentLinkPaymentMethodBankTransfer"}],"discriminator":{"propertyName":"type","mapping":{"bank_transfer":"#/components/schemas/PaymentLinkPaymentMethodBankTransfer"}}},"UserId":{"type":"string","description":"Unique ID for the User","example":"f9b48c9d-176b-46dd-b2da-fe1a2b77350c"},"Address":{"title":"Address","type":"object","properties":{"address_line1":{"type":"string","description":"The full street address including house number and street name.\npattern: `^.{1,50}$``\n","maxLength":50,"example":"40 Finsbury Square","pattern":"^.{1,50}$"},"address_line2":{"type":"string","description":"Further details like building name, suite, apartment number, etc.\npattern: `^.{1,50}$`\n","maxLength":50,"pattern":"^.{1,50}$","example":"The Gilbert"},"city":{"type":"string","description":"Name of the city / locality.\npattern: `^.{1,50}$`\n","maxLength":50,"pattern":"^.{1,50}$","example":"London"},"state":{"type":"string","description":"Name of the county / state.\npattern: `^.{1,50}$`\n","maxLength":50,"pattern":"^.{1,50}$","example":"London"},"zip":{"type":"string","description":"Zip code or postal code.\npattern: `^.{1,20}$`\n","maxLength":20,"pattern":"^.{1,20}$","example":"EC2A 1PX"},"country_code":{"type":"string","description":"The country code according to [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)","minLength":2,"maxLength":2,"example":"GB"}},"required":["address_line1","city","zip","country_code"]},"PaymentLinkUserCreate":{"title":"User","type":"object","description":"Details of the end user who is making the payment.","properties":{"id":{"$ref":"#/components/schemas/UserId","description":"A unique identifier for the user. If you don’t provide this, TrueLayer generates a value in the response. You can use the same value for multiple payments to indicate a returning user."},"name":{"type":"string","example":"Remi Terr","description":"This is the full first and last name of your end user (not initials).\none of `name`/`user_input_config.name` is required.\npattern: `^[^\\(\\)]+$`\n","pattern":"^[^\\(\\)]+$"},"email":{"type":"string","format":"email","example":"remi.terr@aol.com","description":"The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822).\none of `email`/`phone`/`user_input_config.email`/`user_input_config.phone`is required.\n"},"phone":{"type":"string","format":"phone","example":"+447777777777","description":"The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`.\none of `email`/`phone`/`user_input_config.email`/`user_input_config.phone`is required.\n"},"date_of_birth":{"type":"string","format":"date","example":"1990-01-31","description":"The date of birth of your end user, in YYYY-MM-DD format.\n"},"address":{"$ref":"#/components/schemas/Address","description":"The physical address of your end user.\nOnly one of `address`/`user_input_config.address` can be provided.\n"}}},"Metadata":{"type":"object","description":"Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.","maxProperties":10,"additionalProperties":{"type":"string","maxLength":500},"example":{"prop1":"value1","prop2":"value2"}},"PaymentDetails":{"type":"object","title":"Payment Details","required":["amount_in_minor","currency","payment_method","user"],"properties":{"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP or 100 = 1EUR","minimum":1,"example":1},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"payment_method":{"$ref":"#/components/schemas/PaymentLinkMethod"},"user":{"$ref":"#/components/schemas/PaymentLinkUserCreate"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ProductItem":{"title":"Product Item","type":"object","description":"Product details","required":["name","price_in_minor","quantity"],"allOf":[{"type":"object","properties":{"name":{"type":"string","description":"Name of the product.","example":"Oak Table"},"price_in_minor":{"type":"integer","description":"A 'cent' value representing the price of the product. eg 100 == 1GBP or 100 = 1EUR","minimum":0,"example":1},"quantity":{"type":"integer","description":"The product item quantity","minimum":1,"example":1},"url":{"type":"string","description":"Url of the product.","format":"url","example":"https://tablesrus.com/oak-table-42"}}}]},"CreatePaymentLink":{"type":"object","title":"Create payment link","required":["payment_configuration","type"],"properties":{"type":{"type":"string","enum":["single_payment"],"description":"The type of the Payment link"},"expires_at":{"type":"string","description":"The date and time the payment link will expire at.\nIf this property isn't specified, the payment link will expire 24 hours after its creation.\n","format":"datetime","example":"2023-01-22T07:30:53.527Z"},"payment_configuration":{"description":"Configuration of the payment to be created when using the link.\nThis follows the same structure as the create payment request in payments v3 with a couple of distinctions:\n* This configuration only supports `bank_transfer` payment method.\n* This configuration won't allow `data_access_token`.\n","$ref":"#/components/schemas/PaymentDetails"},"product_items":{"type":"array","description":"List of items associated to this link.","items":{"$ref":"#/components/schemas/ProductItem"},"uniqueItems":true,"minItems":1},"reference":{"type":"string","description":"Reference for the payment link. This reference will be shown in the link's UI.\nThis reference won't be shared with the provider or any other third-party.\n","example":"TABLES_R_US_LINK_42"},"return_uri":{"type":"string","description":"This URL determines where the end user will be redirected back once they successfully completed\nthe authorization flow of a payment attempt.\nIf no URL is provided, the end user won't be redirected anywhere, \nbut will instead be shown a TrueLayer's page notifying success.\n","format":"url","example":"https://tablesrus.com/thank-you-for-your-order"}}},"PaymentLinkId":{"type":"string","description":"Unique ID for the Payment Link","example":"aKiW35RWSyF"},"CreatedPaymentLink":{"type":"object","title":"Create payment link Response","required":["uri","id"],"properties":{"id":{"$ref":"#/components/schemas/PaymentLinkId"},"uri":{"type":"string","description":"Link to HPP checkout page.","example":"https://payment.truelayer.com/checkout/aKiW35RWSyF"}}},"ProblemDetailsInvalidParameters":{"title":"Invalid Parameters","type":"object","required":["type","title","status","trace_id","detail","errors"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#invalid-parameters"]},"title":{"type":"string","enum":["Invalid Parameters"]},"status":{"type":"integer","format":"int32","enum":[400]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"The request body was invalid."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"minItems":1},"example":{"beneficiary.type":["Must be either merchant_account or external_account"]}}}},"ProblemDetailsUnauthenticated":{"title":"Unauthenticated","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#unauthenticated"]},"title":{"type":"string","enum":["Unauthenticated"]},"status":{"type":"integer","format":"int32","enum":[401]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"A Bearer token must be provided in the Authorization header."}}},"ProblemDetailsForbidden":{"title":"Forbidden","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#forbidden"]},"title":{"type":"string","enum":["Forbidden"]},"status":{"type":"integer","format":"int32","enum":[403]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"The token used for Authorization is not authorized to perform the request."}}},"ProblemDetailsIdempotencyKeyConcurrencyConflict":{"title":"Idempotency-Key Conflict","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#idempotency-key-concurrency-conflict"]},"title":{"type":"string","enum":["Idempotency-Key Concurrency Conflict"]},"status":{"type":"integer","format":"int32","enum":[409]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"The Idempotency-Key value is being used for a concurrent request."}}},"ProblemDetailsIdempotencyKeyReuse":{"title":"Idempotency-Key Reuse","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#idempotency-key-reuse"]},"title":{"type":"string","enum":["Idempotency-Key Reuse"]},"status":{"type":"integer","format":"int32","enum":[422]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"The Idempotency-Key value has already been used for a different request."}}},"ProblemDetailsRateLimitExceeded":{"title":"Rate Limit Exceeded","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#rate-limit-exceeded"]},"title":{"type":"string","enum":["Rate Limit Exceeded"]},"status":{"type":"integer","format":"int32","enum":[429]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"Too many API requests have been received within the allowed time frame."}}},"ProblemDetailsUnknownError":{"title":"Unknown Error","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#unknown-error"]},"title":{"type":"string","enum":["Unknown Error"]},"status":{"type":"integer","format":"int32","enum":[500]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"An error occurred. Please contact customer support."}}},"PaymentLinkCommon":{"type":"object","required":["id","type"],"properties":{"id":{"$ref":"#/components/schemas/PaymentLinkId"},"type":{"type":"string","enum":["single_payment"],"description":"The type of the Payment link"}}},"PaymentLinkEnabled":{"title":"Enabled","description":"An enabled payment link.\n\nThis is the first status for a payment link.\n","allOf":[{"$ref":"#/components/schemas/PaymentLinkCommon"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["enabled"]}}}]},"PaymentLinkDisabling":{"title":"Disabling","description":"A payment link that can't be used anymore.\nThe link will likely transition to disabled soon.\n\nA link reaching this status is condition based.\nNot every link will reach this status.\nThis status would come after enabled, and before disabled.\n","allOf":[{"$ref":"#/components/schemas/PaymentLinkCommon"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["disabling"]}}}]},"PaymentLinkDisabledReason":{"type":"string","description":"The reason the payment link is disabled.\nExample values to expect:\n- `expired`\n- `fulfilled`\n\nClients should handle unexpected values gracefully.\n","example":"expired"},"PaymentLinkDisabled":{"title":"Disabled","description":"A disabled payment link.\n\nThis is the final status for a payment link.\nNo more payments can be made.\n","allOf":[{"$ref":"#/components/schemas/PaymentLinkCommon"},{"type":"object","required":["status","disabled_reason"],"properties":{"status":{"type":"string","enum":["disabled"]},"disabled_reason":{"$ref":"#/components/schemas/PaymentLinkDisabledReason"}}}]},"GetPaymentLink":{"oneOf":[{"$ref":"#/components/schemas/PaymentLinkEnabled"},{"$ref":"#/components/schemas/PaymentLinkDisabling"},{"$ref":"#/components/schemas/PaymentLinkDisabled"}],"discriminator":{"propertyName":"status","mapping":{"enabled":"#/components/schemas/PaymentLinkEnabled","disabling":"#/components/schemas/PaymentLinkDisabling","disabled":"#/components/schemas/PaymentLinkDisabled"}}},"ProblemDetailsNotFound":{"title":"Not Found","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#not-found"]},"title":{"type":"string","enum":["Not Found"]},"status":{"type":"integer","format":"int32","enum":[404]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"Resource could not be found."}}},"Cursor":{"type":"string","title":"cursor","description":"cursor used for pagination purposes that represents the first item of the page.\nReturned as `next_cursor` in the response payload of endpoints supporting pagination.\nNot required to access the first page of items.\n","example":"bWFuZGF0ZXM6MmUwNDk0MTMK"},"Limit":{"type":"integer","description":"Maximum number of items included in the returned window. Should be greater than 0 and less than 50. If not set, \na default of 25 is considered.\n","default":25,"example":30,"minimum":1,"maximum":50},"PaymentId":{"type":"string","description":"Unique ID for the Payment","example":"0afd1f6a-f611-48ce-9488-321129bb3a70"},"PaymentLinkPaymentPending":{"type":"object","title":"Pending","required":["id","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"status":{"type":"string","enum":["pending"]},"created_at":{"type":"string","description":"The date and time the payment was created at.\n","format":"datetime"}}},"PaymentLinkPaymentSucceeded":{"type":"object","title":"Succeeded","required":["id","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"status":{"type":"string","enum":["succeeded"]},"created_at":{"type":"string","description":"The date and time the payment was created at.\n","format":"datetime"}}},"PaymentLinkPaymentFailed":{"type":"object","title":"Failed","required":["id","status","created_at"],"allOf":[{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"status":{"type":"string","enum":["failed"]},"created_at":{"type":"string","description":"The date and time the payment was created at.\n","format":"datetime"}}}]},"PaymentLinkPayment":{"oneOf":[{"$ref":"#/components/schemas/PaymentLinkPaymentPending"},{"$ref":"#/components/schemas/PaymentLinkPaymentSucceeded"},{"$ref":"#/components/schemas/PaymentLinkPaymentFailed"}]},"NextCursor":{"type":"string","title":"next_cursor","description":"cursor to be used as `cursor` query parameter to fetch the _next page_ in pagination-ready endpoints.","example":"bWFuZGF0ZXM6MmUwNDk0MTMtN2I5Yi00OTFiLWE1OTgtNjkwMzU4NjNjNDJhCg=="},"Pagination":{"title":"pagination","type":"object","properties":{"next_cursor":{"$ref":"#/components/schemas/NextCursor"}},"description":"pagination object.\nOptional next cursor to use as query parameters to fetch the page next to the one fetched.\n","example":{"next_cursor":"bWFuZGF0ZXM6MmUwNDk0MTMK"}},"GetPaymentLinkPayments":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLinkPayment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"SchemeSelectionPreselected":{"title":"Preselected","type":"object","description":"Indicates that the scheme for this payment is preselected.","required":["type","scheme_id"],"properties":{"type":{"type":"string","description":"The type of scheme selection.","enum":["preselected"]},"scheme_id":{"type":"string","description":"The id of the scheme to make the payment over.\n","example":"faster_payments_service"}}},"ProviderSelectionPreselectedSchemeSelection":{"title":"Scheme Selection","type":"object","description":"Scheme Selection","oneOf":[{"$ref":"#/components/schemas/SchemeSelectionInstantOnly"},{"$ref":"#/components/schemas/SchemeSelectionInstantPreferred"},{"$ref":"#/components/schemas/SchemeSelectionPreselected"},{"$ref":"#/components/schemas/SchemeSelectionUserSelected"}],"discriminator":{"propertyName":"type","mapping":{"instant_only":"#/components/schemas/SchemeSelectionInstantOnly","instant_preferred":"#/components/schemas/SchemeSelectionInstantPreferred","preselected":"#/components/schemas/SchemeSelectionPreselected","user_selected":"#/components/schemas/SchemeSelectionUserSelected"}}},"ProviderSelectionPreselectedRemitter":{"title":"Remitter account details","type":"object","description":"Remitter","properties":{"account_holder_name":{"description":"The name of the external account holder. This field will be required if the preselected provider requires it, otherwise it will be optional.\npattern: `^[^\\(\\)]{1,80}$`\n","type":"string","example":"Mike Smith","maxLength":80,"pattern":"^[^\\(\\)]{1,80}$"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"}}},"ProviderSelectionPreselected":{"title":"Preselected","type":"object","description":"Preselected provider. Indicates that the provider for this payment is preselected.","required":["type","provider_id","scheme_selection"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["preselected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment.","example":"eg-provider"},"scheme_selection":{"$ref":"#/components/schemas/ProviderSelectionPreselectedSchemeSelection"},"remitter":{"$ref":"#/components/schemas/ProviderSelectionPreselectedRemitter"},"data_access_token":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*$","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c","description":"If the provider only allows a single active consent across both AIS (data) and PIS (payments) services, in order to prevent invalidating an existing AIS consent, you can pass the data access token in this field, and we will preserve the data consent when requesting authorisation for the payment. \npattern: `^[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*$`\n"}}},"BankTransferProviderSelection":{"title":"Provider Selection","type":"object","description":"Provider Selection","oneOf":[{"$ref":"#/components/schemas/ProviderSelectionUserSelected"},{"$ref":"#/components/schemas/ProviderSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"user_selected":"#/components/schemas/ProviderSelectionUserSelected","preselected":"#/components/schemas/ProviderSelectionPreselected"}}},"BankTransferRetry":{"type":"object","description":"Include this parameter to support retries (only available for GBP payments)"},"PaymentMethodBankTransfer":{"title":"Bank Transfer","type":"object","required":["type","provider_selection","beneficiary"],"properties":{"type":{"type":"string","description":"The type of payment method.","enum":["bank_transfer"]},"provider_selection":{"$ref":"#/components/schemas/BankTransferProviderSelection"},"beneficiary":{"$ref":"#/components/schemas/PaymentDestination"},"retry":{"$ref":"#/components/schemas/BankTransferRetry"}}},"RetryStandard":{"title":"Standard","type":"object","properties":{"type":{"type":"string","description":"Standard retry feature increases payment conversion by automatically retrying payments that failed due to a provider error.\n\nThis feature must be enabled for clients, otherwise the request will fail with a 403 Forbidden status code.\n","enum":["standard"]},"for":{"type":"string","description":"How long to retry this payment for (between `30m` - `6h`).\n\nThis should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively).\n","example":"30m","default":"30m"}},"required":["type"]},"RetrySmart":{"title":"Smart","type":"object","properties":{"type":{"type":"string","description":"Smart retry feature increases payment conversion by automatically retrying failed payments based on various criteria.\n\nThis feature must be enabled for clients, otherwise the request fails with the 403 Forbidden status code.\n","enum":["smart"]},"for":{"type":"string","description":"How long to retry this payment for (between `30m` - `90d`).\n\nThis should be the number followed by a unit (e.g `m`, `h` or `d` for minute, hour or day respectively).\n","example":"1h","default":"24h"},"ensure_minimum_balance_in_minor":{"type":"number","minimum":1,"description":"The payment is attempted only if the remaining balance in the account is at least this amount.\n\nThis should be 'cent' value. eg. 100 = 1GBP.\n\nPayment will only be attempted if the available balance (including any overdrafts) is at least `ensure_minimum_balance_in_minor` + `amount_in_minor`.\n"}},"required":["type"]},"Retry":{"title":"Retry","type":"object","description":"> 🚧 This is an opt-in feature.\n> \n> Please Contact us to enable this feature.\n\nOptional field to enable Retry for this payment.\n\nRetry is performed as frequently as possible based on the nature of the error in order to maximise conversion.\nRead more about [retry here](doc:create-a-payment-on-a-mandate#optional-enable-retries-for-failed-payments).\n","oneOf":[{"$ref":"#/components/schemas/RetryStandard"},{"$ref":"#/components/schemas/RetrySmart"}],"discriminator":{"propertyName":"type","mapping":{"standard":"#/components/schemas/RetryStandard","smart":"#/components/schemas/RetrySmart"}}},"PaymentMethodMandate":{"title":"Mandate","type":"object","required":["type","mandate_id"],"properties":{"type":{"type":"string","description":"The type of payment method.","enum":["mandate"]},"mandate_id":{"type":"string","description":"The identifier of the mandate.\n"},"reference":{"type":"string","description":"Useful for reconciliation needs, it can only be set for mandates with a `beneficiary` type of `external_account`. Recommended max 18 alphanumeric characters.\n"},"retry":{"$ref":"#/components/schemas/Retry"}}},"PaymentMethod":{"title":"Payment Method","type":"object","oneOf":[{"$ref":"#/components/schemas/PaymentMethodBankTransfer"},{"$ref":"#/components/schemas/PaymentMethodMandate"}],"discriminator":{"propertyName":"type","mapping":{"bank_transfer":"#/components/schemas/PaymentMethodBankTransfer","mandate":"#/components/schemas/PaymentMethodMandate"}}},"PaymentUserCreate":{"title":"User","type":"object","description":"Details of the end user who is making the payment. If you are using your own PISP licence, these fields are not required.\n\nPayments over a mandate don't need user information as this was collected at mandate creation.\n","properties":{"id":{"$ref":"#/components/schemas/UserId","description":"A unique identifier for the user. If you don’t provide this, TrueLayer generates a value in the response. You can use the same value for multiple payments to indicate a returning user."},"name":{"type":"string","example":"Remi Terr","description":"This is the full first and last name of your end user (not initials).\nIf you are using your own PISP licence this field is optional, otherwise it is required.\npattern: `^[^\\(\\)]+$`\n","pattern":"^[^\\(\\)]+$"},"email":{"type":"string","format":"email","example":"remi.terr@aol.com","description":"The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822).\nIf you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required.\n"},"phone":{"type":"string","format":"phone","example":"+447777777777","description":"The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`.\nIf you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required.\n"},"date_of_birth":{"type":"string","format":"date","example":"1990-01-31","description":"The date of birth of your end user, in YYYY-MM-DD format."},"address":{"$ref":"#/components/schemas/Address","description":"The physical address of your end user."},"political_exposure":{"type":"string","enum":["current","none"],"example":"current","description":"The user's political exposure (PEP), if known this field should be set to `current` otherwise to `none`.\n\nIf not known this field can be ignored or a `null` value can be sent.\n"}}},"RelatedProducts":{"type":"object","description":"Optional field for adding related products, at least one product should be set.\nNot available when creating recurring payments.\n","properties":{"signup_plus":{"type":"object","description":"Signup+ product.\n"}},"example":{"signup_plus":{}}},"Icon":{"title":"Icon","type":"object","properties":{"type":{"type":"string","description":"Configuration for the type of icon. Available options are:\n- `default`: Default icon with no background (SVG).\n- `extended`: Extended as a square with an appropriate background colour (SVG).\n- `extended_small`: Extended icon with 192x192 px size (JPEG).\n- `extended_medium`: Extended icon with 432x432 px size (JPEG).\n- `extended_large`: Extended icon jpeg with 864x864 px size (JPEG).\n","enum":["default","extended","extended_small","extended_medium","extended_large"]}}},"AdditionalInputType":{"type":"string","enum":["text","text_with_image","select"],"description":"Possible input types for the `form` action:\n * `text` - The end user must enter some text\n * `text_with_image` - The end user must enter some text with an accompanying image (e.g. QR code)\n * `select` - The end user must select an option\n"},"ConsentSupportedPis":{"type":"object","title":"PIS Consent"},"AisScope":{"type":"string","title":"AIS Scope","enum":["accounts","balance"]},"ConsentSupportedAis":{"type":"object","title":"AIS Consent","properties":{"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AisScope"},"minItems":1,"uniqueItems":true}},"required":["scopes"]},"ConsentSupported":{"type":"object","title":"Consent Requirements","description":"The details of the consents supported to be captured from the user.","properties":{"pis":{"$ref":"#/components/schemas/ConsentSupportedPis"},"ais":{"$ref":"#/components/schemas/ConsentSupportedAis"}},"required":["pis"]},"StartPaymentAuthorizationFlow":{"type":"object","description":"This object contains a declaration of the client UI's capabilities. The API will adjust the flow depending on this declaration and filter out unsupported providers.\n","properties":{"provider_selection":{"type":"object","description":"Can your UI render a provider selection screen?\n\nIn payments where you set provider_selection as user_selected, your UI must be able to render a screen where the user can select their payments provider. This parameter is required for payments with user_selected provider selection. For preselected provider selection, it's optional.\n\nUse the provider_selection.filter parameter at payment creation to determine the list of providers you can choose to display in your UI.\n","properties":{"icon":{"$ref":"#/components/schemas/Icon"}}},"scheme_selection":{"type":"object","description":"Can your UI render a scheme selection screen?\n\nFor payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme.\n\nThis field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional.\n"},"redirect":{"type":"object","description":"Can your UI redirect the user to a third-party page?\n\nFor most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect.\n","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"During the flow, the end user authorises the payment on a third-party site, such as a bank. The return_uri you set is where the user is redirected to after they complete authorisation on the third-party site.\n\nYou must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris).\n","format":"url"},"direct_return_uri":{"type":"string","description":"Only applicable if you're regulated and have a direct return URI registered with UK providers.\n\nIf you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your page without going via TrueLayer.\n\nWe recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a Truelayer domain.\n","format":"url"}}},"form":{"type":"object","description":"Can your UI render form inputs for the user to interact with?\n\nSome providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs.\n\nThis parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. \n\nIf the provider has been preselected and requires additional inputs, this field is required.\n","properties":{"input_types":{"type":"array","description":"The types of input that your UI can render a form to collect.","items":{"$ref":"#/components/schemas/AdditionalInputType"},"uniqueItems":true,"minItems":1,"example":["text"]}},"required":["input_types"]},"consent":{"type":"object","description":"Can your UI capture the user's consent?\n\nThis parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment.\n\nIf you omit this, the API may restrict the available providers if explicit consent is required.\n","properties":{"action_type":{"type":"string","description":"How you will capture consent as part of the authorisation flow:\n- `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow.\n- `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions.\n","enum":["explicit","adjacent"]},"requirements":{"$ref":"#/components/schemas/ConsentSupported"}}},"user_account_selection":{"type":"object","description":"Can your UI render a user account selection screen?\n\nIf the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments.\n\nThis field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option.\n"}},"example":{"provider_selection":{},"scheme_selection":{},"redirect":{"return_uri":"https://my-site.com/payment-return"},"form":{"input_types":["text"]},"consent":{},"user_account_selection":{}}},"HostedPageParameters":{"title":"Hosted Page Parameters","description":"Provide these parameters to have an auto constructed [hosted page](https://docs.truelayer.com/docs/hosted-payment-page) URI returned on the response.\n\nThis cannot be provided if starting the `authorization_flow` explicitly.\n","type":"object","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"The URI where the user will be redirected to after the authorization flow has completed on the hosted page.\nYou must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris).\n","format":"url","example":"https://my-domain.com/my-return-page"},"country_code":{"type":"string","description":"The country code of the user. This is used to determine which banks to show on the hosted page initially.\nThe country code must be in ISO 3166-1 alpha-2 format.\n","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$","example":"GB"},"language_code":{"type":"string","description":"The language code of the user. This is used to determine which language to show on the hosted page, overriding the browser's locale.\nThe language code must be in ISO 639-1 format.\n","minLength":2,"maxLength":2,"pattern":"^[a-z]{2}$","example":"en"},"max_wait_for_result":{"type":"integer","description":"The maximum time to wait for a result from the hosted page after the user has completed the authorization flow, in seconds.\n","minimum":0,"maximum":60,"example":3}}},"RiskAssessment":{"type":"object","description":"An optional field for configuring risk assessment and the `payment_creditable` webhook. [Learn how to enable this field](/docs/payment-risk-and-credit-notifications#multiple-payment_creditable-behaviours-with-the-segment-parameter).\n","properties":{"segment":{"type":"string","example":"Flights","description":"The risk segment of this payment. Please contact us before sending this field.\npattern: `^[^\\(\\)]+$`\n","pattern":"^[^\\(\\)]+$"}}},"UltimateCounterpartyBusinessDivision":{"title":"Business Division","type":"object","description":"The business details of the ultimate counterparty.","required":["type","id","name"],"properties":{"type":{"type":"string","description":"The ultimate counterparty is a division of the main business.","enum":["business_division"]},"id":{"type":"string","description":"The identifier of the business division.\n"},"name":{"type":"string","description":"The name of the business division.\n"}}},"UltimateCounterpartyBusinessClient":{"title":"Business Client","type":"object","description":"The business details of the ultimate counterparty.","required":["type","trading_name"],"properties":{"type":{"type":"string","description":"The ultimate counterparty is a registered business.","enum":["business_client"]},"trading_name":{"type":"string","description":"The trading name of the business.\npattern: `^.{1,70}$`\n","maxLength":70,"pattern":"^.{1,70}$"},"commercial_name":{"type":"string","description":"The commercial name of the business.\npattern: `^.{1,100}$`\n","maxLength":100,"pattern":"^.{1,100}$"},"url":{"type":"string","description":"The website of the business. This must be a valid URL.","maxLength":100,"example":"https://truelayer.com"},"mcc":{"type":"string","description":"The merchant category code of the business.\npattern: `^[0-9]{4}$`\n","maxLength":4,"pattern":"^[0-9]{4}$","example":"1234"},"registration_number":{"type":"string","description":"The registration number of the business.\n\nThis is required if `address` is not provided.\npattern: `^.{1,35}$`\n","maxLength":35,"pattern":"^.{1,35}$"},"address":{"$ref":"#/components/schemas/Address","description":"The address of the business.\n\nThis is required if `registration_number` is not provided.\n"}}},"PaymentUltimateCounterparty":{"oneOf":[{"$ref":"#/components/schemas/UltimateCounterpartyBusinessDivision"},{"$ref":"#/components/schemas/UltimateCounterpartyBusinessClient"}],"discriminator":{"propertyName":"type","mapping":{"business_division":"#/components/schemas/UltimateCounterpartyBusinessDivision","business_client":"#/components/schemas/UltimateCounterpartyBusinessClient"}}},"PaymentSubMerchants":{"title":"Sub Merchants","type":"object","description":"The details related to any applicable sub-merchants, for example an underlying division of the overall business.","required":["ultimate_counterparty"],"properties":{"ultimate_counterparty":{"$ref":"#/components/schemas/PaymentUltimateCounterparty"}}},"UserConsentPrecapturedRequest":{"title":"Precaptured","type":"object","description":"The consent has been captured prior to the payment being created.","required":["type","captured_at"],"properties":{"type":{"type":"string","description":"The consent has been captured prior to the payment being created.","enum":["precaptured"]},"captured_at":{"type":"string","description":"The date and time the consent was captured.","format":"datetime"}}},"UserConsentAuthorizationFlowCapturedRequest":{"title":"Authorization Flow Captured","type":"object","description":"The consent will be captured as part of the payment authorization flow.","required":["type"],"properties":{"type":{"type":"string","description":"The consent will be captured as part of the payment authorization flow.","enum":["authorization_flow_captured"]}}},"UserConsentRequest":{"title":"User Consent","type":"object","description":"Information of how the user's consent is captured for the payment.","oneOf":[{"$ref":"#/components/schemas/UserConsentPrecapturedRequest"},{"$ref":"#/components/schemas/UserConsentAuthorizationFlowCapturedRequest"}],"discriminator":{"propertyName":"type","mapping":{"precaptured":"#/components/schemas/UserConsentPrecapturedRequest","authorization_flow_captured":"#/components/schemas/UserConsentAuthorizationFlowCapturedRequest"}}},"CreatePayment":{"type":"object","title":"Create payment","required":["amount_in_minor","currency","payment_method","user"],"properties":{"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 = 1GBP or 100 = 1EUR","minimum":1,"example":1},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"user":{"$ref":"#/components/schemas/PaymentUserCreate"},"metadata":{"$ref":"#/components/schemas/Metadata"},"related_products":{"$ref":"#/components/schemas/RelatedProducts"},"authorization_flow":{"$ref":"#/components/schemas/StartPaymentAuthorizationFlow","description":"This object contains a declaration of your UI's capabilities. The API adjusts the flow based on this parameter and filters out unsupported providers. If you supply this parameter, you don't need to call the [**Start authorization flow** endpoint](/reference/start-payment-authorization-flow).\n\nThis cannot be provided if also using the `hosted_page` option.\n"},"hosted_page":{"$ref":"#/components/schemas/HostedPageParameters"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"sub_merchants":{"$ref":"#/components/schemas/PaymentSubMerchants"},"user_consent":{"$ref":"#/components/schemas/UserConsentRequest"}}},"PaymentUser":{"title":"User","type":"object","required":["id"],"properties":{"id":{"$ref":"#/components/schemas/UserId"}}},"PaymentCreatedCommon":{"title":"Newly created payment","type":"object","required":["id","user","resource_token"],"properties":{"id":{"type":"string","description":"ID of the payment","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"},"user":{"description":"Details on the user of the created payment. If the user_id was not passed in the request body while creating\nthe payment, an ID will be generated and returned in this response\n","$ref":"#/components/schemas/PaymentUser"},"resource_token":{"type":"string","description":"A payment token in JWT format, with a limited scope that is authorised to be used with a single payment","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50X2lkIjoiMGFmZDFmNmEtZjYxMS00OGNlLTk0ODgtMzIxMTI5YmIzYTcwIiwiaWF0IjoxNTE2MjM5MDIyfQ.awUcg4OfxW8lNGB0HUdSfcEpCAiMg_zHudX95EsqvtE"}}},"HostedPage":{"title":"Hosted Page","description":"Returned if the `hosted_page` object in the request body is populated.\n","type":"object","required":["uri"],"properties":{"uri":{"type":"string","description":"The URI to redirect the user to authorize the payment using the hosted page.\n","format":"url","example":"https://payment.truelayer.com/payments?lng=en#payment_id=0afd1f6a-f611-48ce-9488-321129bb3a70&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50X2lkIjoiMGFmZDFmNmEtZjYxMS00OGNlLTk0ODgtMzIxMTI5YmIzYTcwIiwiaWF0IjoxNTE2MjM5MDIyfQ.awUcg4OfxW8lNGB0HUdSfcEpCAiMg_zHudX95EsqvtE&return_uri=https%3A%2F%2Fmy-domain.com%2Fmy-return-page"}}},"PaymentCreatedAuthorizationRequired":{"title":"Authorization Required","allOf":[{"$ref":"#/components/schemas/PaymentCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorization_required"]},"hosted_page":{"$ref":"#/components/schemas/HostedPage"}},"required":["status"]}]},"ProviderId":{"type":"string","description":"Unique ID for the Provider","example":"ob-bank-name"},"SchemeId":{"type":"string","description":"The unique identifier for the scheme.","example":"faster_payments_service"},"PaymentsProviderScheme":{"title":"Scheme","type":"object","properties":{"id":{"$ref":"#/components/schemas/SchemeId"}},"required":["id"]},"ProviderStatus":{"type":"string","enum":["healthy","unhealthy"]},"ProviderAvailability":{"type":"object","title":"Provider Availability","description":"Whether the provider is currently available.\n> 🚧 This feature is in beta\n","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":{"id":{"$ref":"#/components/schemas/ProviderId"},"display_name":{"type":"string","example":"Bank Name"},"icon_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg"},"logo_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg"},"bg_color":{"type":"string","description":"pattern: `^#[A-F0-9]{6}$`","pattern":"^#[A-F0-9]{6}$","example":"#000000"},"schemes":{"type":"array","description":"List of schemes supported by the provider.","items":{"$ref":"#/components/schemas/PaymentsProviderScheme"}},"availability":{"$ref":"#/components/schemas/ProviderAvailability","description":"Whether the provider is currently available.\n> 🚧 This feature is in beta\n"},"country_code":{"$ref":"#/components/schemas/CountryCode"},"search_aliases":{"type":"array","description":"Alternative search terms that should be used to help users find this provider.","items":{"type":"string"}}}},"ActionSpecProviderSelection":{"type":"object","title":"Provider Selection","description":"Provider selection represents the PSU action of selecting a provider\n","properties":{"type":{"type":"string","enum":["provider_selection"]},"providers":{"type":"array","description":"List of providers to be presented to the PSU","items":{"$ref":"#/components/schemas/Provider"}}},"required":["type","providers"]},"Scheme":{"title":"Scheme","type":"object","properties":{"id":{"$ref":"#/components/schemas/SchemeId"},"recommended":{"type":"boolean","description":"Whether the scheme has been recommended for use for this particular payment."},"fee":{"type":"object","properties":{"amount_in_minor":{"type":"integer","description":"The fee amount that applies to this payment, expressed in the minor unit of the currency.","minimum":1,"example":1},"currency":{"type":"string","description":"The currency of the fee.","example":"EUR"}},"required":["amount_in_minor","currency"]}},"required":["id","recommended"]},"ActionSpecSchemeSelection":{"type":"object","title":"Scheme Selection","description":"Scheme selection represents the PSU action of selecting a scheme\n","properties":{"type":{"type":"string","enum":["scheme_selection"]},"schemes":{"type":"array","description":"List of schemes to be presented to the PSU","items":{"$ref":"#/components/schemas/Scheme"}}},"required":["type","schemes"]},"ActionSpecRedirect":{"type":"object","title":"Redirect","properties":{"type":{"type":"string","enum":["redirect"]},"uri":{"type":"string","format":"url","description":"URL the end user must be redirected to.\n"}},"required":["type","uri"]},"DisplayText":{"type":"object","title":"Display Text","properties":{"default":{"type":"string","description":"A value that can be used as a default to show to the user, if the key cannot be used to look up a relevant value.","example":"Please enter your IBAN"},"key":{"type":"string","description":"A key that is intended to be used as a translation key to look up and render localised text. If a key is not provided, it indicates that this value cannot be localised and that the `default` value should always be preferred.","example":"remitter_iban_display_label"}},"required":["default"]},"ActionSpecWaitForOutcome":{"type":"object","title":"Wait for Outcome","description":"Indication that there are currently no actions to perform.\nClients must poll the GET '/v3/payment/{id}' endpoint until the status changes, or the next action is available.\n","properties":{"type":{"type":"string","enum":["wait"]},"display_message":{"$ref":"#/components/schemas/DisplayText","description":"An optional message to be displayed to the end user while they are waiting."}},"required":["type"]},"AdditionalInputCommon":{"type":"object","properties":{"id":{"type":"string","description":"The identifier for the additional input, to be used when submitting the user's value back to the API."},"mandatory":{"type":"boolean","description":"Whether or not a value for this input must be provided when the form is submitted.","example":true},"display_text":{"$ref":"#/components/schemas/DisplayText","description":"The text to be used as a label for the input, to be rendered in the UI somewhere alongside the input itself."},"description":{"$ref":"#/components/schemas/DisplayText","description":"Additional text that provides more information about the input and the value that the PSU is expected to provide."}},"required":["id","mandatory","display_text"]},"TextAdditionalInputCommon":{"allOf":[{"$ref":"#/components/schemas/AdditionalInputCommon"},{"type":"object","properties":{"format":{"type":"string","description":"The type of text input that this represents.","enum":["any","numerical","alphabetical","alphanumerical","email","sort_code","account_number","iban"]},"sensitive":{"type":"boolean","description":"Whether or not the input contains sensitive information (e.g. a password). This can be used to render a field in the UI that masks input.","example":true},"min_length":{"type":"integer","description":"The minimum length (inclusive) of the text input value.","example":1},"max_length":{"type":"integer","description":"The maximum length (inclusive) of the text input value.","example":40},"regexes":{"type":"array","description":"A collection of regexes to validate the input against.","items":{"type":"object","properties":{"regex":{"type":"string","description":"A regular expression for defining the accepted format of the text input.","example":"^[\\w\\d ]$"},"message":{"$ref":"#/components/schemas/DisplayText","description":"A validation message to show if the text input does not match the corresponding regex."}},"required":["regex","message"]}}},"required":["format","sensitive","min_length","max_length"]}]},"TextAdditionalInput":{"title":"Text","allOf":[{"$ref":"#/components/schemas/TextAdditionalInputCommon"},{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"]}]},"Image":{"oneOf":[{"title":"URI","type":"object","properties":{"type":{"type":"string","enum":["uri"]},"uri":{"type":"string"}},"required":["type","uri"]},{"title":"Base 64","type":"object","properties":{"type":{"type":"string","enum":["base64"]},"data":{"type":"string"},"media_type":{"type":"string"}},"required":["type","data","media_type"]}]},"TextWithImageAdditionalInput":{"title":"Text With Image","allOf":[{"$ref":"#/components/schemas/TextAdditionalInputCommon"},{"type":"object","properties":{"type":{"type":"string","enum":["text_with_image"]},"image":{"$ref":"#/components/schemas/Image"}},"required":["type","image"]}]},"SelectAdditionalInput":{"title":"Select","allOf":[{"$ref":"#/components/schemas/AdditionalInputCommon"},{"type":"object","properties":{"type":{"type":"string","enum":["select"]},"options":{"type":"array","description":"Exhaustive list of values to select from.\n","items":{"type":"object","properties":{"id":{"type":"string","description":"The identifier of the option, this is the value to be submitted back to the API.","example":"branch-a"},"display_text":{"$ref":"#/components/schemas/DisplayText","description":"The value to show to the PSU in the UI select dropdown."},"search_aliases":{"type":"array","description":"Alternative search terms for this option.","items":{"type":"string"}}},"required":["id","display_text"]}}},"required":["type","options"]}]},"ActionSpecAdditionalInput":{"oneOf":[{"$ref":"#/components/schemas/TextAdditionalInput"},{"$ref":"#/components/schemas/TextWithImageAdditionalInput"},{"$ref":"#/components/schemas/SelectAdditionalInput"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TextAdditionalInput","text_with_image":"#/components/schemas/TextWithImageAdditionalInput","select":"#/components/schemas/SelectAdditionalInput"}}},"ActionSpecForm":{"type":"object","title":"Form","description":"Form action represents the PSU action of entering further details into the UI.\n","properties":{"type":{"type":"string","enum":["form"]},"inputs":{"type":"array","description":"The inputs to be presented to the PSU in the UI.","items":{"$ref":"#/components/schemas/ActionSpecAdditionalInput"},"uniqueItems":true,"minItems":1}},"required":["type","inputs"]},"ConsentRequirementsPis":{"type":"object","title":"PIS Consent"},"ConsentRequirementsAis":{"type":"object","title":"AIS Consent","properties":{"required_scopes":{"type":"array","items":{"$ref":"#/components/schemas/AisScope"},"uniqueItems":true},"optional_scopes":{"type":"array","items":{"$ref":"#/components/schemas/AisScope"},"uniqueItems":true}},"required":["required_scopes","optional_scopes"]},"ConsentRequirements":{"type":"object","title":"Consent Requirements","description":"The details of the consents required to be captured from the user.","properties":{"pis":{"$ref":"#/components/schemas/ConsentRequirementsPis"},"ais":{"$ref":"#/components/schemas/ConsentRequirementsAis"}}},"ActionSpecConsent":{"type":"object","title":"Consent","properties":{"type":{"type":"string","enum":["consent"]},"requirements":{"$ref":"#/components/schemas/ConsentRequirements"},"subsequent_action_hint":{"type":"string","enum":["redirect","form","wait"]}},"required":["subsequent_action_hint","type","requirements"]},"BranchId":{"type":"string","description":"Unique ID for the branch","example":"xs2a-branch-id"},"Branch":{"type":"object","title":"Branch","description":"A specific branch of a provider.","properties":{"id":{"$ref":"#/components/schemas/BranchId"}},"required":["id"]},"UserAccountDetails":{"type":"object","properties":{"id":{"type":"string","description":"The identifier of the saved user account details.","example":"25bf2298-9b79-43ab-8896-331b9c44c27f"},"provider":{"$ref":"#/components/schemas/Provider"},"branch":{"$ref":"#/components/schemas/Branch"},"masked_account_identifier":{"type":"string","description":"A masked representation of the saved account identifier.","example":"******12"},"last_used_at":{"type":"string","description":"The date and time of when this account was used.","format":"datetime","example":"2022-12-01T15:12:35.123Z"}},"required":["id","provider","masked_account_identifier","last_used_at"]},"ActionSpecUserAccountSelection":{"type":"object","title":"User Account Selection","description":"Provides the end user with a list of previously saved user accounts for reuse.\n","properties":{"type":{"type":"string","enum":["user_account_selection"]},"user_accounts":{"type":"array","description":"List of user accounts to be presented to the PSU","items":{"$ref":"#/components/schemas/UserAccountDetails"}}},"required":["type","user_accounts"]},"RetryOption":{"type":"string","enum":["Restart"],"example":"Restart"},"ActionSpecRetry":{"type":"object","title":"Retry","properties":{"type":{"type":"string","enum":["retry"]},"retry_options":{"type":"array","description":"List of retry options available","items":{"$ref":"#/components/schemas/RetryOption"}}},"required":["type","retry_options"]},"NextAction":{"oneOf":[{"$ref":"#/components/schemas/ActionSpecProviderSelection"},{"$ref":"#/components/schemas/ActionSpecSchemeSelection"},{"$ref":"#/components/schemas/ActionSpecRedirect"},{"$ref":"#/components/schemas/ActionSpecWaitForOutcome"},{"$ref":"#/components/schemas/ActionSpecForm"},{"$ref":"#/components/schemas/ActionSpecConsent"},{"$ref":"#/components/schemas/ActionSpecUserAccountSelection"},{"$ref":"#/components/schemas/ActionSpecRetry"}],"discriminator":{"propertyName":"type","mapping":{"provider_selection":"#/components/schemas/ActionSpecProviderSelection","scheme_selection":"#/components/schemas/ActionSpecSchemeSelection","redirect":"#/components/schemas/ActionSpecRedirect","wait":"#/components/schemas/ActionSpecWaitForOutcome","form":"#/components/schemas/ActionSpecForm","consent":"#/components/schemas/ActionSpecConsent","user_account_selection":"#/components/schemas/ActionSpecUserAccountSelection","retry":"#/components/schemas/ActionSpecRetry"}},"description":"The next action can be performed via `POST /v3/payments/{id}/authorization_flow/action/{action_name}` -\ncheck its documentation for relevant examples.\n"},"AdjacentActions":{"type":"object","title":"Adjacent Actions","description":"Actions that can be submitted alongside the next action","properties":{"consent":{"type":"object","properties":{"requirements":{"$ref":"#/components/schemas/ConsentRequirements"}},"required":["requirements"]}}},"PaymentAuthorizationFlow":{"type":"object","title":"Authorization Flow","description":"Contains information regarding the nature and the state of the authorization flow \n","required":["actions"],"properties":{"actions":{"type":"object","required":["next"],"properties":{"next":{"$ref":"#/components/schemas/NextAction"},"adjacent":{"$ref":"#/components/schemas/AdjacentActions"}}}}},"PaymentCreatedAuthorizing":{"title":"Authorizing","allOf":[{"$ref":"#/components/schemas/PaymentCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorizing"]},"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlow","description":"Contains information regarding the nature and the state of the authorization flow. This object will have a value only if in the request body the authorization_flow field was specified."}},"required":["status","authorization_flow"]}]},"PaymentCreatedAuthorized":{"title":"Authorized","allOf":[{"$ref":"#/components/schemas/PaymentCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorized"]}},"required":["status"]}]},"PaymentFailureStage":{"type":"string","enum":["authorization_required","authorizing","authorized","executed"],"description":"The status the payment was in when it failed.\n","example":"authorizing"},"PaymentFailureReason":{"type":"string","description":"The <a href=\"https://docs.truelayer.com/docs/single-payment-statuses#failure-reasons\" target=\"_blank\">reason</a> that the payment failed.\n","example":"provider_rejected"},"PaymentCreatedFailed":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/PaymentCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"failure_stage":{"$ref":"#/components/schemas/PaymentFailureStage"},"failure_reason":{"$ref":"#/components/schemas/PaymentFailureReason"}},"required":["status","failure_stage","failure_reason"]}]},"CreatedPayment":{"oneOf":[{"$ref":"#/components/schemas/PaymentCreatedAuthorizationRequired"},{"$ref":"#/components/schemas/PaymentCreatedAuthorizing"},{"$ref":"#/components/schemas/PaymentCreatedAuthorized"},{"$ref":"#/components/schemas/PaymentCreatedFailed"}],"discriminator":{"propertyName":"status","mapping":{"authorization_required":"#/components/schemas/PaymentCreatedAuthorizationRequired","authorizing":"#/components/schemas/PaymentCreatedAuthorizing","authorized":"#/components/schemas/PaymentCreatedAuthorized","failed":"#/components/schemas/PaymentCreatedFailed"}}},"PaymentAuthorizationFlowAuthorizing":{"title":"Authorizing","allOf":[{"type":"object","required":["authorization_flow"],"properties":{"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlow"}}},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authorizing"]}}}]},"PaymentAuthorizationFlowAuthorizationFailed":{"title":"Failed","allOf":[{"type":"object","required":["status","failure_stage","failure_reason"],"properties":{"status":{"type":"string","enum":["failed"]},"failure_stage":{"$ref":"#/components/schemas/PaymentFailureStage"},"failure_reason":{"$ref":"#/components/schemas/PaymentFailureReason"}}}]},"PerformPaymentAction":{"oneOf":[{"$ref":"#/components/schemas/PaymentAuthorizationFlowAuthorizing"},{"$ref":"#/components/schemas/PaymentAuthorizationFlowAuthorizationFailed"}],"discriminator":{"propertyName":"status","mapping":{"authorizing":"#/components/schemas/PaymentAuthorizationFlowAuthorizing","failed":"#/components/schemas/PaymentAuthorizationFlowAuthorizationFailed"}}},"ProblemDetailsInvalidState":{"title":"Invalid State","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#invalid_state"]},"title":{"type":"string","enum":["Invalid State"]},"status":{"type":"integer","format":"int32","enum":[400]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"Status of the payment does not allow this action to be executed."}}},"ProblemDetailsConcurrencyConflict":{"title":"Concurrency Conflict","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#concurrency-conflict"]},"title":{"type":"string","enum":["Concurrency Conflict"]},"status":{"type":"integer","format":"int32","enum":[409]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"The resource is already used by another request."}}},"PerformActionProviderSelection":{"title":"Provider selection","type":"object","required":["provider_id"],"properties":{"provider_id":{"type":"string","example":"mock-payments-gb-redirect"}}},"PerformActionSchemeSelection":{"title":"Scheme selection","type":"object","required":["scheme_id"],"properties":{"scheme_id":{"type":"string","example":"faster_payments_service","description":"The id of the scheme to make the payment over."}}},"ConsentCapturedPis":{"type":"object","title":"PIS Consent"},"ConsentCapturedAis":{"type":"object","title":"AIS Consent","properties":{"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AisScope"},"minItems":1,"uniqueItems":true}},"required":["scopes"]},"AdjacentConsentCaptured":{"type":"object","title":"Adjacent Consent Captured","description":"The details of the consents captured from the user.\n","properties":{"pis":{"$ref":"#/components/schemas/ConsentCapturedPis"},"ais":{"$ref":"#/components/schemas/ConsentCapturedAis"}},"required":["pis"]},"AdjacentActionsSubmission":{"type":"object","title":"Adjacent Actions","description":"Optionally submit adjacent actions","properties":{"consent":{"type":"object","title":"Consent Captured","description":"Indicate consent was captured alongside this action","properties":{"captured":{"$ref":"#/components/schemas/AdjacentConsentCaptured"}},"required":["captured"]}}},"SubmitForm":{"type":"object","properties":{"inputs":{"description":"A dictionary of input values, where the key matches one returned previously in the form action and the value represents the associated value provided by the end user.","additionalProperties":{"x-additionalPropertiesName":"input_id","type":"string","description":"The value of the input identified by the key, as entered by the end user."},"example":{"branch-id":"branch-abc-1","branch-code":"BRNC-789"}},"adjacent":{"$ref":"#/components/schemas/AdjacentActionsSubmission"}},"required":["inputs"]},"ProblemDetailsProviderError":{"title":"Provider Error","type":"object","required":["type","title","status","trace_id","detail"],"properties":{"type":{"type":"string","enum":["https://docs.truelayer.com/docs/payments-api-errors#provider-error"]},"title":{"type":"string","enum":["Provider Error"]},"status":{"type":"integer","format":"int32","enum":[502]},"trace_id":{"type":"string","description":"The TrueLayer trace identifier for the request","example":"96ce50247f87f540bb2d86771b3728b8"},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"Provider is temporarily unavailable, please retry."}}},"ConsentCaptured":{"type":"object","title":"Consent Captured","description":"The details of the consents captured from the user.\nIf omitted it is assumed a standard PIS consent was captured.\n","properties":{"pis":{"$ref":"#/components/schemas/ConsentCapturedPis"},"ais":{"$ref":"#/components/schemas/ConsentCapturedAis"}},"required":["pis"]},"SubmitConsent":{"type":"object","title":"Submit consent","description":"Indicate consent was captured","properties":{"captured":{"$ref":"#/components/schemas/ConsentCaptured"}}},"SubmitUserAccountSelectionNew":{"title":"New","type":"object","properties":{"type":{"type":"string","enum":["new"]}},"required":["type"]},"SubmitUserAccountSelectionExisting":{"title":"Existing","type":"object","properties":{"type":{"type":"string","enum":["existing"]},"user_account_id":{"type":"string","description":"The identifier of the saved account details that have been chosen for re-use.","example":"25bf2298-9b79-43ab-8896-331b9c44c27f"}},"required":["type","user_account_id"]},"SubmitUserAccountSelectionDelete":{"title":"Delete","type":"object","properties":{"type":{"type":"string","enum":["delete"]},"user_account_id":{"type":"string","description":"The identifier of the saved account details that have been chosen to be removed.","example":"25bf2298-9b79-43ab-8896-331b9c44c27f"}},"required":["type","user_account_id"]},"SubmitUserAccountSelection":{"title":"Submit User Account Selection","type":"object","oneOf":[{"$ref":"#/components/schemas/SubmitUserAccountSelectionNew"},{"$ref":"#/components/schemas/SubmitUserAccountSelectionExisting"},{"$ref":"#/components/schemas/SubmitUserAccountSelectionDelete"}],"discriminator":{"propertyName":"type","mapping":{"new":"#/components/schemas/SubmitUserAccountSelectionNew","existing":"#/components/schemas/SubmitUserAccountSelectionExisting","delete":"#/components/schemas/SubmitUserAccountSelectionDelete"}}},"ProviderFilterResponse":{"title":"Provider Filter","type":"object","description":"Configuration options to constrain which providers should be available\nduring the `provider_selection` action.\n\n_**Note:** This field is required when OAuth2 token is used._\n","properties":{"countries":{"type":"array","description":"Only providers from the specified countries will be returned.","items":{"$ref":"#/components/schemas/CountryCode"},"uniqueItems":true,"minItems":1,"example":["GB"]},"release_channel":{"type":"string","description":"The lowest stability release stage of a provider that should be returned.","enum":["general_availability","public_beta","private_beta"],"example":"general_availability"},"customer_segments":{"type":"array","description":"The customer segments catered to by a provider that should be returned.","items":{"type":"string","enum":["retail","business","corporate"]},"uniqueItems":true,"minItems":1,"example":["retail"]},"provider_ids":{"type":"array","description":"IDs of providers to include in those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["mock-payments-gb-redirect"]},"excludes":{"type":"object","description":"Options to exclude providers included by the filters","properties":{"provider_ids":{"type":"array","description":"IDs of providers to explicitly exclude from those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["ob-exclude-this-bank"]}}}}},"ProviderSelectionUserSelectedResponse":{"title":"User selected","type":"object","description":"Indicates that the user selects the provider that they want to pay with from a list.","required":["type"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["user_selected"]},"filter":{"$ref":"#/components/schemas/ProviderFilterResponse"},"scheme_selection":{"$ref":"#/components/schemas/ProviderSelectionUserSelectedSchemeSelection"},"provider_id":{"type":"string","description":"The provider ID that the end user uses for this payment. Populated when provider selection has been submitted.","example":"eg-provider"},"scheme_id":{"type":"string","description":"The id of the scheme to make the payment over. If you fetch information about a payment using a GET request, you always receive a response that includes a `scheme_id` if a payment has reached the `authorized` status or later.","example":"payment_scheme"}}},"PaymentAccountIdentifierResponse":{"title":"Account Identifier","oneOf":[{"$ref":"#/components/schemas/AccountIdentifierScan"},{"$ref":"#/components/schemas/AccountIdentifierIban"},{"$ref":"#/components/schemas/AccountIdentifierNrb"}],"discriminator":{"propertyName":"type","mapping":{"sort_code_account_number":"#/components/schemas/AccountIdentifierScan","iban":"#/components/schemas/AccountIdentifierIban","nrb":"#/components/schemas/AccountIdentifierNrb"}},"description":"A unique account identifier for an external account.\n\n_**Note:** This field is required when OAuth2 token is used._\n"},"RemitterResponse":{"title":"Remitter account details","type":"object","description":"Remitter\n\n_**Note:** This field is required when OAuth2 token is used._\n","properties":{"account_holder_name":{"description":"The name of the external account holder.","type":"string","example":["Mike Smith"]},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifierResponse"}}},"ProviderSelectionPreselectedResponse":{"title":"Preselected","type":"object","description":"Preselected provider. Indicates that the provider for this payment is preselected.","required":["type","provider_id"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["preselected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment.","example":"eg-provider"},"scheme_id":{"type":"string","description":"The id of the scheme to make the payment over.","example":"payment_scheme"},"scheme_selection":{"$ref":"#/components/schemas/ProviderSelectionPreselectedSchemeSelection"},"remitter":{"$ref":"#/components/schemas/RemitterResponse"}}},"BankTransferProviderSelectionResponse":{"title":"Provider Selection","type":"object","description":"Provider Selection","oneOf":[{"$ref":"#/components/schemas/ProviderSelectionUserSelectedResponse"},{"$ref":"#/components/schemas/ProviderSelectionPreselectedResponse"}]},"MerchantAccountIdResponse":{"type":"string","description":"Unique ID for the Merchant Account\n    \n_**Note:** This field is required when OAuth2 token is used._\n"},"PaymentDestinationMerchantAccountResponse":{"type":"object","title":"Merchant Account","description":"The identifier for a TrueLayer's merchant account.","required":["type"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["merchant_account"]},"merchant_account_id":{"description":"The unique identifier of a TrueLayer merchant account.\n\n_**Note:** This field is required when OAuth2 token is used._\n","$ref":"#/components/schemas/MerchantAccountIdResponse"},"account_holder_name":{"description":"The name of the beneficiary, which displays in the remitter's bank statement.\nIf unspecified, the API uses the account owner name associated with the selected merchant account.\n","type":"string"},"reference":{"description":"A reference for the payment. Not visible to the remitter.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$`\n","type":"string","maxLength":100,"example":"payment-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$"},"verification":{"description":"The verification of the remitter info. If specified, the API performs additional checks on the remitter information. \n","$ref":"#/components/schemas/Verification"},"statement_reference":{"description":"Payment reference that should be set on the end user's statement. Not all banks support setting such a reference, this value will be used wherever possible.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$`\n","type":"string","maxLength":18,"example":"payment-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]+$"}}},"PaymentDestinationExternalAccountResponse":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","reference"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["external_account"]},"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifierResponse"},"reference":{"type":"string"}}},"PaymentDestinationResponse":{"oneOf":[{"$ref":"#/components/schemas/PaymentDestinationMerchantAccountResponse"},{"$ref":"#/components/schemas/PaymentDestinationExternalAccountResponse"}]},"BankTransferRetryResponse":{"type":"object","description":"This parameter indicate that the payment support retries (only available for GBP payments)"},"PaymentMethodBankTransferResponse":{"title":"Bank Transfer","type":"object","required":["type","provider_selection","beneficiary"],"properties":{"type":{"type":"string","description":"The type of payment method.","enum":["bank_transfer"]},"provider_selection":{"$ref":"#/components/schemas/BankTransferProviderSelectionResponse"},"beneficiary":{"$ref":"#/components/schemas/PaymentDestinationResponse"},"retry":{"$ref":"#/components/schemas/BankTransferRetryResponse"}}},"PaymentMethodResponse":{"title":"Payment Method","type":"object","oneOf":[{"$ref":"#/components/schemas/PaymentMethodBankTransferResponse"},{"$ref":"#/components/schemas/PaymentMethodMandate"}],"discriminator":{"propertyName":"type","mapping":{"bank_transfer":"#/components/schemas/PaymentMethodBankTransferResponse","mandate":"#/components/schemas/PaymentMethodMandate"}}},"UserConsentPrecapturedResponse":{"title":"Precaptured","type":"object","description":"The consent has been captured prior to the payment being created.","required":["type"],"properties":{"type":{"type":"string","description":"The consent has been captured prior to the payment being created.","enum":["precaptured"]},"captured_at":{"type":"string","description":"The date and time the consent was captured.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime"}}},"UserConsentAuthorizationFlowCapturedResponse":{"title":"Authorization Flow Captured","type":"object","description":"The consent will be captured as part of the payment authorization flow.","required":["type"],"properties":{"type":{"type":"string","description":"The consent will be captured as part of the payment authorization flow.","enum":["authorization_flow_captured"]}}},"UserConsentResponse":{"title":"User Consent","type":"object","description":"Information of how the user's consent is captured for the payment.","oneOf":[{"$ref":"#/components/schemas/UserConsentPrecapturedResponse"},{"$ref":"#/components/schemas/UserConsentAuthorizationFlowCapturedResponse"}],"discriminator":{"propertyName":"type","mapping":{"precaptured":"#/components/schemas/UserConsentPrecapturedResponse","authorization_flow_captured":"#/components/schemas/UserConsentAuthorizationFlowCapturedResponse"}}},"PaymentCommon":{"type":"object","required":["id","amount_in_minor","currency","beneficiary","payment_method"],"properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"amount_in_minor":{"type":"integer","minimum":1},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"user":{"$ref":"#/components/schemas/PaymentUser"},"payment_method":{"$ref":"#/components/schemas/PaymentMethodResponse"},"created_at":{"type":"string","description":"The date and time the payment was created at.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime"},"metadata":{"$ref":"#/components/schemas/Metadata"},"related_products":{"$ref":"#/components/schemas/RelatedProducts"},"sub_merchants":{"$ref":"#/components/schemas/PaymentSubMerchants"},"user_consent":{"$ref":"#/components/schemas/UserConsentResponse"}}},"PaymentAuthorizationRequired":{"title":"Authorization Required","description":"A payment yet to be authorized.\n\nThis is the first status for a payment that requires further actions\nto be authorized.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authorization_required"]}}}]},"PaymentAuthorizationFlowConfiguration":{"type":"object","title":"Configuration","properties":{"provider_selection":{"type":"object","description":"Can your UI render a provider selection screen?\n\nIn payments where you set `provider_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments provider. Use the `provider_selection.filter` parameter to determine which providers display in your UI.\n\nThis parameter is required for payments with `user_selected` provider selection. For `preselected` provider selection, it's optional.\n"},"scheme_selection":{"type":"object","description":"Can your UI render a scheme selection screen?\n\nFor payments where you set `scheme_selection` as `user_selected`, your UI must be able to render a screen where the user can select their payments scheme.\n\nThis field is required for payments with `user_selected` scheme selection. For other scheme selection types, it's optional.\n"},"redirect":{"type":"object","description":"Can your UI redirect the user to a third-party page?\n\nFor most providers, the user authorises the payment after they're redirected to their chosen provider's page. There, they can sign in with their credentials and approve the payment. This parameter states whether your UI can handle such a redirect.\n","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"During the authorization flow the end user might be redirected to another page, such as a bank website or TrueLayer's Hosted Payment Page.\n\nThis URL determines where the API redirects the user to after they complete the flow on the third-party's website. You must register the `return_uri` in your [settings in Console](/docs/app-settings#allowed-redirect-uris).\n","format":"url"},"direct_return_uri":{"type":"string","description":"Only applicable if you're regulated and have a direct return URI registered with UK providers.\n\nIf you're regulated, you can specify a `direct_return_uri` to attempt the authorization flow via a direct redirect from the provider authorization page to your without going via TrueLayer.\n\nWe recommend that your `return_uri` is a URI that can handle a non-direct return scenario. This ensures that if the `direct_return_uri` isn't registered with the user's chosen provider, the payment can still be authorized through a Truelayer domain.\n","format":"url"}}},"form":{"type":"object","description":"Can your UI render form inputs for the user to interact with?\n\nSome providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization. To facilitate this, the API may return a `form` action as part of the authorization flow, which means your UI must be able to collect the required inputs.\n\nThis parameter states whether your UI supports the `form` action. If you omit this parameter, the API returns only providers that don't require additional inputs. \n\nIf the provider has been preselected and requires additional inputs, this field is required.\n","properties":{"input_types":{"type":"array","description":"The types of input that your UI can render a form to collect.","items":{"$ref":"#/components/schemas/AdditionalInputType"},"uniqueItems":true,"minItems":1,"example":["text"]}},"required":["input_types"]},"consent":{"type":"object","description":"Can your UI capture the user's consent?\n\nThis parameter states whether your UI can explicitly capture and report the end user's consent for initiating the payment.\n\nIf you omit this, the API may restrict the available providers if explicit consent is required.\n","properties":{"action_type":{"type":"string","description":"How you will capture consent as part of the authorisation flow:\n- `explicit` (default): The authorisation flow returns an explicit `consent` action for you to respond to at an appropriate moment in the flow.\n- `adjacent`: You provide the consent information alongside other actions in the flow. This enables the UI to combine capturing consent alongside with other actions, if you indicate consent is gathered when you respond to those actions. Note this is currently only supported on `form` actions.\n","enum":["explicit","adjacent"]},"requirements":{"$ref":"#/components/schemas/ConsentSupported"}}},"user_account_selection":{"type":"object","description":"Can your UI render a user account selection screen?\n\nIf the user has previously consented to saving their bank account details with TrueLayer, they can choose from their saved accounts to speed up following payments.\n\nThis field states whether your UI can render a selection screen for these saved accounts. If you omit this, the user isn't presented with this option.\n"}}},"PaymentAuthorizing":{"title":"Authorizing","description":"A payment yet to be authorized.\n\nThis is the first status for a payment that requires further actions\nto be authorized.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","required":["status","authorization_flow"],"properties":{"status":{"type":"string","enum":["authorizing"]},"authorization_flow":{"allOf":[{"$ref":"#/components/schemas/PaymentAuthorizationFlow"},{"type":"object","properties":{"configuration":{"$ref":"#/components/schemas/PaymentAuthorizationFlowConfiguration"}}}]}}}]},"PaymentAuthorizationFlowFrozen":{"type":"object","title":"Authorization Flow","description":"Information about the authorization flow the payment went through.\n\nIf the payment transitioned immediately to `authorized` or `failed`,\nthis field will be null.\n","required":["configuration"],"properties":{"configuration":{"$ref":"#/components/schemas/PaymentAuthorizationFlowConfiguration"}}},"AccountIdentifier":{"title":"Account Identifier","oneOf":[{"$ref":"#/components/schemas/AccountIdentifierScan"},{"$ref":"#/components/schemas/AccountIdentifierIban"},{"$ref":"#/components/schemas/AccountIdentifierNrb"}],"discriminator":{"propertyName":"type","mapping":{"sort_code_account_number":"#/components/schemas/AccountIdentifierScan","iban":"#/components/schemas/AccountIdentifierIban","nrb":"#/components/schemas/AccountIdentifierNrb"}},"description":"A unique scheme identifier for an external account.\n"},"PaymentSource":{"title":"Payment source","type":"object","description":"Information about the source of funds,  if available from the remitter's bank. Account identifiers will be those provided by the bank.","properties":{"account_holder_name":{"type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}},"required":["account_holder_name","account_identifiers"]},"CreditableAt":{"type":"string","description":"The date and time that TrueLayer determined that the payment was ready to be credited.","format":"datetime","example":"2023-06-13T15:00:00.000Z"},"PaymentAuthorized":{"title":"Authorized","description":"An authorized payment - no more actions required, waiting for outcome.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorized"]},"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlowFrozen"},"payment_source":{"$ref":"#/components/schemas/PaymentSource"},"creditable_at":{"$ref":"#/components/schemas/CreditableAt"}},"required":["status"]}]},"SettlementStalledAt":{"type":"string","description":"The date and time at which TrueLayer determined that the payment's settlement was stalled based on the client's chosen delay or the default one.\n","format":"datetime","example":"2023-06-13T15:00:00.000Z"},"DisputedAt":{"type":"string","description":"The date and time that TrueLayer received an indemnity claim for the payment.","format":"datetime","example":"2023-06-13T15:00:00.000Z"},"DisputedReason":{"type":"string","description":"The reason that the indemnity claim was made against the payment."},"PaymentExecuted":{"title":"Executed","description":"An executed payment.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["executed"]},"executed_at":{"type":"string","description":"The date and time the payment executed at.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime"},"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlowFrozen"},"payment_source":{"$ref":"#/components/schemas/PaymentSource"},"creditable_at":{"$ref":"#/components/schemas/CreditableAt"},"settlement_stalled_at":{"$ref":"#/components/schemas/SettlementStalledAt"},"disputed_at":{"$ref":"#/components/schemas/DisputedAt"},"disputed_reason":{"$ref":"#/components/schemas/DisputedReason"}},"required":["status"]}]},"SettledPaymentSource":{"title":"Settled Payment source","type":"object","properties":{"id":{"type":"string","format":"uuid","example":"e2b41c9d-176k-67aa-b2da-fe1a2b97253c"},"account_holder_name":{"type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}},"required":["id","account_holder_name","account_identifiers"]},"ReversedAt":{"type":"string","description":"Date and time the payment was reversed.","format":"datetime","example":"2023-06-13T15:00:00.000Z"},"ReversalReason":{"type":"string","enum":["corrected","failed","disputed"],"description":"The reason for the payment reversal.\n","example":"corrected"},"PaymentSettled":{"title":"Settled","description":"A settled payment. i.e. the funds have settled into the beneficiary account. Status only available for payments into merchant accounts.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["settled"]},"payment_source":{"$ref":"#/components/schemas/SettledPaymentSource","description":"Source of funds.\n\n_**Note:** This field is required when OAuth2 token is used._\n"},"executed_at":{"type":"string","description":"Date and time the payment executed.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime"},"settled_at":{"type":"string","description":"Date and time the payment settled.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime"},"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlowFrozen"},"creditable_at":{"$ref":"#/components/schemas/CreditableAt"},"settlement_stalled_at":{"$ref":"#/components/schemas/SettlementStalledAt"},"disputed_at":{"$ref":"#/components/schemas/DisputedAt"},"disputed_reason":{"$ref":"#/components/schemas/DisputedReason"},"reversed_at":{"$ref":"#/components/schemas/ReversedAt"},"reversal_reason":{"$ref":"#/components/schemas/ReversalReason"}},"required":["status","executed_at"]}]},"PaymentFailureFundsStage":{"type":"string","enum":["received","not_received"],"description":"The status of the funds when the payment failed.\n","example":"received"},"PaymentFailed":{"title":"Failed","description":"A failed payment - it was authorized successfully, but the money did not move.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"failed_at":{"type":"string","description":"The date and time the payment was marked as failed.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_stage":{"$ref":"#/components/schemas/PaymentFailureStage"},"failure_reason":{"$ref":"#/components/schemas/PaymentFailureReason"},"failure_funds_stage":{"$ref":"#/components/schemas/PaymentFailureFundsStage","description":"This is populated for Direct Debit payments only."},"authorization_flow":{"$ref":"#/components/schemas/PaymentAuthorizationFlowFrozen"},"payment_source":{"$ref":"#/components/schemas/PaymentSource"},"creditable_at":{"$ref":"#/components/schemas/CreditableAt"},"settlement_stalled_at":{"$ref":"#/components/schemas/SettlementStalledAt"},"reversed_at":{"$ref":"#/components/schemas/ReversedAt"},"reversal_reason":{"$ref":"#/components/schemas/ReversalReason"}},"required":["status","failure_stage","failure_reason"]}]},"PaymentAttemptFailed":{"title":"Attempt Failed","description":"A failed payment attempt - it was authorized successfully, but the money did not move.\n","allOf":[{"$ref":"#/components/schemas/PaymentCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["attempt_failed"]},"failed_at":{"type":"string","description":"The date and time the payment was marked as failed.\n\n_**Note:** This field is required when OAuth2 token is used._\n","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_stage":{"$ref":"#/components/schemas/PaymentFailureStage"},"failure_reason":{"$ref":"#/components/schemas/PaymentFailureReason"},"authorization_flow":{"allOf":[{"$ref":"#/components/schemas/PaymentAuthorizationFlow"},{"type":"object","properties":{"configuration":{"$ref":"#/components/schemas/PaymentAuthorizationFlowConfiguration"}}}]},"payment_source":{"$ref":"#/components/schemas/PaymentSource"}},"required":["status","failure_stage","failure_reason"]}]},"GetPayment":{"oneOf":[{"$ref":"#/components/schemas/PaymentAuthorizationRequired"},{"$ref":"#/components/schemas/PaymentAuthorizing"},{"$ref":"#/components/schemas/PaymentAuthorized"},{"$ref":"#/components/schemas/PaymentExecuted"},{"$ref":"#/components/schemas/PaymentSettled"},{"$ref":"#/components/schemas/PaymentFailed"},{"$ref":"#/components/schemas/PaymentAttemptFailed"}],"discriminator":{"propertyName":"status","mapping":{"authorization_required":"#/components/schemas/PaymentAuthorizationRequired","authorizing":"#/components/schemas/PaymentAuthorizing","authorized":"#/components/schemas/PaymentAuthorized","executed":"#/components/schemas/PaymentExecuted","settled":"#/components/schemas/PaymentSettled","failed":"#/components/schemas/PaymentFailed","attempt_failed":"#/components/schemas/PaymentAttemptFailed"}}},"MerchantAccountCurrencyCode":{"type":"string","enum":["GBP","EUR","PLN"],"example":"GBP"},"SearchProviderCapabilities":{"type":"object","description":"Options for capabilities of the providers.","properties":{"payments":{"description":"Only providers with `payments` capabilities will be returned.","type":"object","properties":{"bank_transfer":{"description":"Only providers with `bank transfer` capability will be returned.","type":"object"}}},"mandates":{"description":"Only providers with `mandates` capabilities will be returned.","type":"object","properties":{"vrp_sweeping":{"description":"Only providers with `sweeping` capability will be returned.","type":"object"},"vrp_commercial":{"description":"Only providers with `commercial` capability will be returned.","type":"object"}}}}},"SearchPaymentsProvidersAuthorizationFlow":{"title":"Direct Integration","type":"object","required":["configuration"],"properties":{"configuration":{"type":"object","description":"Options for the authorization flow configuration of the customized UI.\nThis should be the same object you use in the start authorization flow request body.\n","properties":{"provider_selection":{"type":"object","description":"Can your UI render a provider selection screen?\n\nIn payments where you set provider_selection as user_selected, your UI must be able to render a screen where the user can select their payments provider. This parameter is required for payments with user_selected provider selection. For preselected provider selection, it's optional.\n\nUse the provider_selection.filter parameter at payment creation to determine the list of providers you can choose to display in your UI.\n","properties":{"icon":{"$ref":"#/components/schemas/Icon"}}},"redirect":{"type":"object","description":"Can the UI redirect the end user to a third-party page?\n\nFor most providers, payment authorization is achieved by redirecting the user to their chosen provider's page, where they can sign in with their credentials and approve the payment.\nThis field declares whether the UI is able to perform such a redirect.\n"},"form":{"required":["input_types"],"type":"object","description":"Can the UI render form inputs for the end user to interact with?\n\nSome providers require additional inputs, such as the remitter name and account details, to be provided before or during payment authorization.\nTo facilitate this, the API may return a `form` action as part of the authorization flow, prompting the UI to collect the required inputs.\n\nThis field declares whether the UI supports the `form` action.\nIf it is omitted, only providers that do not require additional inputs will be returned. \nIf the provider has been preselected and requires additional inputs, this field is considered mandatory.\n","properties":{"input_types":{"type":"array","description":"The types of input that the UI is able to render","items":{"$ref":"#/components/schemas/AdditionalInputType"},"uniqueItems":true,"minItems":1,"example":["text"]}}},"consent":{"type":"object","description":"Can the UI capture the user's consent?\n\nThis field declares whether the UI supports explicitly capturing and reporting the end user's consent for initiating the payment.\nIf it is omitted, the providers available may be restricted if explicit consent is required.\n","properties":{"requirements":{"$ref":"#/components/schemas/ConsentSupported"}}}}}}},"SearchPaymentsProvidersRequest":{"type":"object","title":"Search payment providers","required":["authorization_flow"],"properties":{"countries":{"type":"array","description":"Only providers from the specified countries will be returned.","items":{"$ref":"#/components/schemas/CountryCode"},"uniqueItems":true,"minItems":1,"example":["GB"]},"currencies":{"description":"Only schemes that support at least one of the specified currencies will be returned.","type":"array","uniqueItems":true,"minItems":1,"items":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"}},"release_channel":{"type":"string","description":"Only capabilities that are at least on the specified release channel will be returned.\n\nNote that many European providers are in `public_beta` or `private_beta`.\n","default":"general_availability","enum":["general_availability","public_beta","private_beta"],"example":"general_availability"},"customer_segments":{"type":"array","description":"Only providers that cater to at least one of the specified customer segments will be returned.","items":{"type":"string","enum":["retail","business","corporate"]},"uniqueItems":true,"minItems":1,"example":["retail"]},"capabilities":{"$ref":"#/components/schemas/SearchProviderCapabilities"},"authorization_flow":{"$ref":"#/components/schemas/SearchPaymentsProvidersAuthorizationFlow"}}},"ProviderReleaseChannel":{"type":"string","enum":["general_availability","public_beta","private_beta","alpha"]},"PaymentsProvidersSchemeRequirements":{"title":"Requirement","type":"object","properties":{"currencies":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyCode"}},"account_identifier_types":{"type":"array","items":{"type":"string","enum":["iban","bban","sort_code_account_number","nrb"]}}},"required":["account_identifier_types","currencies"]},"PaymentsProvidersScheme":{"title":"Scheme","type":"object","properties":{"id":{"$ref":"#/components/schemas/SchemeId"},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/PaymentsProvidersSchemeRequirements"}}},"required":["id","requirements"]},"PaymentsProvidersCapabilities":{"type":"object","description":"Describes the capabilities of this provider.\nBy default, will only display capabilities in `general_availability` or `public beta`.\nIf `client_id` is available, will display capabilities available to the client.\n","properties":{"payments":{"description":"Single payment initiation capabilities.","type":"object","properties":{"bank_transfer":{"description":"Bank transfer capability.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"},"availability":{"$ref":"#/components/schemas/ProviderAvailability","description":"Provider availability"},"schemes":{"description":"List of payment schemes supported by this provider.","type":"array","items":{"$ref":"#/components/schemas/PaymentsProvidersScheme"}}},"required":["release_channel","schemes"]}}},"mandates":{"description":"Recurring payment mandate creation capabilities.","type":"object","properties":{"vrp_sweeping":{"description":"Mandates for the sweeping use case.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"},"availability":{"$ref":"#/components/schemas/ProviderAvailability","description":"Provider availability"}},"required":["release_channel"]},"vrp_commercial":{"description":"Mandates for the commercial use case.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"},"availability":{"$ref":"#/components/schemas/ProviderAvailability","description":"Provider availability"}},"required":["release_channel"]}}}}},"ProviderBins":{"type":"array","description":"A list of BIN (Bank Identification Numbers) ranges supported by the provider.\nBased on the ISO/IEC 7812-1:2017 BIN refers to the first eight numbers on a payment card, identifying the financial institution that issues the card.\n","items":{"type":"object","description":"A range of valid BINs that determine the inclusive starting and ending numbers.\n","properties":{"from":{"description":"The starting number of the BIN range (inclusive).\nA valid integer must represent the first eight digits of a payment card number.\n","type":"integer","format":"int32","example":51685900},"to":{"description":"The ending number of the BIN range (inclusive).\nA valid integer must represent the first eight digits of a payment card number.\n","type":"integer","format":"int32","example":51685999}},"required":["from","to"]}},"PaymentsProvidersProvider":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ProviderId"},"display_name":{"type":"string","example":"Bank Name"},"icon_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg"},"logo_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg"},"bg_color":{"type":"string","description":"pattern: `^#[A-F0-9]{6}$`","pattern":"^#[A-F0-9]{6}$","example":"#000000"},"country_code":{"$ref":"#/components/schemas/CountryCode"},"swift_code":{"type":"string","description":"ISO 9362 international standard for Business Identifier Codes (BIC)","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","example":"MOCKGB01XXX"},"capabilities":{"$ref":"#/components/schemas/PaymentsProvidersCapabilities"},"bin_ranges":{"$ref":"#/components/schemas/ProviderBins"}},"required":["id","capabilities"]},"SearchPaymentsProviders":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentsProvidersProvider"}}}},"ProviderCapabilities":{"type":"object","description":"Describes the capabilities of this provider.\nBy default, will only display capabilities in `general_availability` or `public beta`.\nIf `client_id` is available, will display capabilities available to the client.\n","properties":{"payments":{"description":"Single payment initiation capabilities.","type":"object","properties":{"bank_transfer":{"description":"Bank transfer capability.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"},"availability":{"$ref":"#/components/schemas/ProviderAvailability","description":"Whether the provider is currently available.\n> 🚧 This feature is in beta\n"},"schemes":{"description":"List of payment schemes supported by this provider.","type":"array","items":{"$ref":"#/components/schemas/PaymentsProviderScheme"}}},"required":["release_channel","schemes"]}}},"mandates":{"description":"Recurring payment mandate creation capabilities.","type":"object","properties":{"vrp_sweeping":{"description":"Mandates for the sweeping use case.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"}},"required":["release_channel"]},"vrp_commercial":{"description":"Mandates for the commercial use case.","type":"object","properties":{"release_channel":{"description":"Release channel of the provider and capability.","$ref":"#/components/schemas/ProviderReleaseChannel"}},"required":["release_channel"]}}}}},"PaymentsProvider":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ProviderId"},"display_name":{"type":"string","example":"Bank Name"},"icon_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg"},"logo_uri":{"type":"string","format":"uri","example":"https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg"},"bg_color":{"type":"string","description":"pattern: `^#[A-F0-9]{6}$`","pattern":"^#[A-F0-9]{6}$","example":"#000000"},"country_code":{"$ref":"#/components/schemas/CountryCode"},"swift_code":{"type":"string","description":"ISO 9362 international standard for Business Identifier Codes (BIC)","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","example":"MOCKGB01XXX"},"capabilities":{"$ref":"#/components/schemas/ProviderCapabilities"},"bin_ranges":{"$ref":"#/components/schemas/ProviderBins"}},"required":["id","capabilities"]},"PaymentRefundId":{"type":"string","description":"Unique ID for the refund","example":"43d12d0f-d775-410f-aaff-482200c17017"},"PaymentRefundCommon":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PaymentRefundId"},"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP","minimum":1},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"reference":{"type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["id","amount_in_minor","currency","reference"]},"PaymentRefundPending":{"title":"Pending","type":"object","description":"The refund has been created against TrueLayer's API but\nit has not yet been authorized and sent to the payment scheme for execution.\n","allOf":[{"$ref":"#/components/schemas/PaymentRefundCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]},"created_at":{"type":"string","description":"The date and time the refund was created","format":"datetime"}},"required":["status","created_at"]}]},"PaymentRefundAuthorized":{"title":"Authorized","type":"object","description":"The refund has been authorized (i.e. there are enough funds) and\nit has been submitted to the payment scheme for execution.\n","allOf":[{"$ref":"#/components/schemas/PaymentRefundCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorized"]},"created_at":{"type":"string","description":"The date and time the refund was created","format":"datetime"}},"required":["status","created_at"]}]},"PaymentRefundExecuted":{"title":"Executed","type":"object","description":"The refund was executed - the funds have left your merchant account.\n","allOf":[{"$ref":"#/components/schemas/PaymentRefundCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["executed"]},"created_at":{"type":"string","description":"The date and time the refund was created","format":"datetime"},"executed_at":{"type":"string","description":"The date and time the refund transitioned to `executed`","format":"datetime"}},"required":["status","created_at","executed_at"]}]},"OutboundPaymentFailureReason":{"type":"string","description":"The reason the outbound payment failed.\nExample values to expect:\n- `insufficient_funds`\n- `scheme_error`\n- `server_error`\n- `blocked`\n- `returned`\n- `account_not_valid`: the bank account(s) associated to the given AIS consent is/are not valid. Note that this error is only relevant for `user_determined` beneficiaries.\n- `expired`: the user did not authorize the payout within the required timeframe. This error applies only to `user_determined` beneficiaries.\n- `verification_name_mismatch`: the name provided as part of a payout verification does not match the one available on the connected bank account\n- `verification_transaction_not_found`: the transaction details provided as part of a payout verification are not found within the associated bank account's transactions\n\nClients should handle unexpected values gracefully as a unknown failure.\n","example":"insufficient_funds"},"PaymentRefundFailed":{"title":"Failed","type":"object","description":"The refund failed - the funds have not left your merchant account.\n","allOf":[{"$ref":"#/components/schemas/PaymentRefundCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"created_at":{"type":"string","description":"The date and time the refund was created","format":"datetime"},"executed_at":{"type":"string","description":"The date and time the refund transitioned to `executed`","format":"datetime"},"failed_at":{"type":"string","description":"The date and time the refund transitioned to `failed`","format":"datetime"},"failure_reason":{"$ref":"#/components/schemas/OutboundPaymentFailureReason"}},"required":["status","created_at","failed_at","failure_reason"]}]},"PaymentRefund":{"oneOf":[{"$ref":"#/components/schemas/PaymentRefundPending"},{"$ref":"#/components/schemas/PaymentRefundAuthorized"},{"$ref":"#/components/schemas/PaymentRefundExecuted"},{"$ref":"#/components/schemas/PaymentRefundFailed"}],"discriminator":{"propertyName":"status","mapping":{"pending":"#/components/schemas/PaymentRefundPending","authorized":"#/components/schemas/PaymentRefundAuthorized","executed":"#/components/schemas/PaymentRefundExecuted","failed":"#/components/schemas/PaymentRefundFailed"}}},"GetPaymentRefunds":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRefund"}}}},"CreatePaymentRefund":{"type":"object","title":"Create payment refund","properties":{"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP.","minimum":1},"reference":{"type":"string","description":"A reference for the refund."},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["reference"]},"PaymentRefundCreated":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PaymentRefundId"}},"required":["id"]},"PayoutIncomingDestinationExternalAccount":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","account_identifier","reference"],"properties":{"type":{"type":"string","description":"Type \"external_account\"","enum":["external_account"]},"reference":{"description":"The reference for the payout, which displays in the beneficiary's bank statement.\n\nFor SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n\nFor FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,’+\\s#=!\"%&*<>;{@\\r\\n]*$`\n\nFor Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,'+\\s]*$`\n","type":"string"},"account_holder_name":{"description":"The name of the external account holder.\n\nFor SEPA payments, the maximum length is **70 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n\nFor FPS payments, the maximum length is **140 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,’+\\s#=!\"%&*<>;{@\\r\\n]*$`\n\nFor Elixir payments, the maximum length is **70 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,'+\\s]*$`\n","type":"string"},"account_identifier":{"$ref":"#/components/schemas/AccountIdentifier"},"date_of_birth":{"type":"string","format":"date","example":"1990-01-31","description":"If the client's transactions are subject to sanctions screening, they must provide the `date_of_birth` (in YYYY-MM-DD format), otherwise it is optional."},"address":{"$ref":"#/components/schemas/Address","description":"If the client's transactions are subject to sanctions screening, they must provide the `address`, otherwise it is optional."}}},"PayoutIncomingDestinationPaymentSource":{"title":"Payment Source","type":"object","required":["type","user_id","payment_source_id","reference"],"properties":{"type":{"type":"string","description":"Type \"payment_source\"","enum":["payment_source"]},"reference":{"type":"string","description":"A reference for the payout."},"payment_source_id":{"type":"string","description":"ID of the external account which has become a payment source."},"user_id":{"type":"string","description":"ID of the owning user of the external account."}}},"PayoutIncomingDestinationBusinessAccount":{"title":"Business Account","type":"object","required":["type","reference"],"properties":{"type":{"type":"string","description":"Type \"business_account\" payed to a preconfigured business IBAN.","enum":["business_account"]},"reference":{"type":"string","description":"A reference for the payout."}}},"PayoutUserCreate":{"title":"User","type":"object","description":"Details of the beneficiary of the payment.\n","properties":{"id":{"$ref":"#/components/schemas/UserId","description":"A unique identifier for the user. If you don’t provide this, TrueLayer generates a value in the response. You can use the same value for multiple payments to indicate a returning user."},"name":{"type":"string","example":"Remi Terr","description":"This is the full first and last name of your end user (not initials).\nThis field is required if at least one of the following conditions is met: \n- your client id is not regulated;\n- `verification.verify_name` is set to `true`\n","pattern":"^[^\\(\\)]+$"},"email":{"type":"string","format":"email","example":"remi.terr@aol.com","description":"The email address of your end user according to [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822).\nIf you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required.\n"},"phone":{"type":"string","format":"phone","example":"+447777777777","description":"The phone number of your end user in formats recommended by [ITU](https://www.itu.int/oth/T0202.aspx?parent=T0202). The country calling code must be included and prefixed with a `+`.\nIf you are using your own PISP licence this field is optional, otherwise one of `email`/`phone` is required.\n"},"date_of_birth":{"type":"string","format":"date","example":"1990-01-31","description":"The date of birth of your end user, in YYYY-MM-DD format."},"address":{"$ref":"#/components/schemas/Address","description":"The physical address of your end user."}}},"PayoutBeneficiaryVerificationTransactionSearchCriteria":{"type":"object","description":"An object describing the search criteria to use to look for a transaction in the transaction history\nof the bank account connected to the end user\n","required":["tokens","amount_in_minor","currency","created_at"],"properties":{"tokens":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","minLength":3,"maxLength":50},"description":"A list of tokens to look for as transaction reference. \nThe size of this array can vary between 1 and 5 items. \nEach item should present minimum 3 and maximum 50 characters, including spaces.\nWe recommend adding the merchant's name and an identifier in the transaction's description.\neg `[\"18db38\", \"Betropolis LTD\", \"LC Betropolis\"]`\n","example":["18db38","Betropolis LTD","LC Betropolis"]},"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP","minimum":1,"example":115},"currency":{"type":"string","description":"The currency that the payout will be in.","enum":["GBP"]},"created_at":{"type":"string","description":"The date the transaction was created at. eg `\"2024-05-07\"`","format":"date"}}},"PayoutIncomingBeneficiaryVerification":{"type":"object","description":"Object that describes the verification checks to run on the payout. At least one between `account_holder_name` and `transaction_search_criteria` must be specified.","required":["verify_name"],"properties":{"verify_name":{"description":"Enable verification for the account holder name.\n\n_**Note:** This is expected to always be `true`. In future this will be made optional to support verification types that don't involve checking account holder names._\n","type":"boolean"},"transaction_search_criteria":{"$ref":"#/components/schemas/PayoutBeneficiaryVerificationTransactionSearchCriteria"}}},"ProviderFilter-2":{"title":"Provider Filter","type":"object","description":"Configuration options to constrain which providers should be available\nduring the `provider_selection` action.\n","properties":{"countries":{"type":"array","description":"Only providers from the specified countries will be returned.","items":{"type":"string","enum":["GB"]},"uniqueItems":true,"minItems":1,"example":["GB"]},"release_channel":{"type":"string","description":"The lowest stability release stage of a provider that should be returned.","default":"general_availability","enum":["general_availability","public_beta","private_beta"],"example":"general_availability"},"provider_ids":{"type":"array","description":"IDs of providers to include in those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["mock-payments-gb-redirect"]},"excludes":{"type":"object","description":"Options to exclude providers included by the filters","properties":{"provider_ids":{"type":"array","description":"IDs of providers to explicitly exclude from those returned.","items":{"type":"string"},"uniqueItems":true,"minItems":1,"example":["ob-exclude-this-bank"]}}}}},"PayoutProviderSelectionUserSelected":{"title":"User selected","type":"object","description":"Indicates that the provider is to be selected from a collection","required":["type"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["user_selected"]},"filter":{"$ref":"#/components/schemas/ProviderFilter-2"}}},"PayoutProviderSelectionPreselected":{"title":"Preselected","type":"object","description":"Preselected provider. Indicates that the provider for this payment is preselected.","required":["type","provider_id"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["preselected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment.","example":"eg-provider"}}},"PayoutProviderSelection":{"title":"Payout provider Selection","type":"object","description":"Provider Selection used for `User Determined` beneficiaries","oneOf":[{"$ref":"#/components/schemas/PayoutProviderSelectionUserSelected"},{"$ref":"#/components/schemas/PayoutProviderSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"user_selected":"#/components/schemas/PayoutProviderSelectionUserSelected","preselected":"#/components/schemas/PayoutProviderSelectionPreselected"}}},"PayoutIncomingDestinationUserDetermined":{"type":"object","title":"User Determined","description":"Beneficiary details of type User Determined","required":["type","reference","user","verification","provider_selection"],"properties":{"type":{"type":"string","description":"Represents a beneficiary that is specified by the end-user.","enum":["user_determined"]},"reference":{"description":"The reference for the payout, which displays in the beneficiary's bank statement.\n\nFor SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n\nFor FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,’+\\s#=!\"%&*<>;{@\\r\\n]*$`\n\nFor Elixir payments, the maximum length is **20 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,'+\\s]*$`\n","type":"string"},"user":{"$ref":"#/components/schemas/PayoutUserCreate"},"verification":{"description":"Object that represents the verification process associated to the payout. Used in _Verified Payouts_.\n\n_**Note:** This field might be made optional in future to support multiple `User Determined` use cases._\n","$ref":"#/components/schemas/PayoutIncomingBeneficiaryVerification"},"provider_selection":{"$ref":"#/components/schemas/PayoutProviderSelection"}}},"PayoutIncomingDestination":{"oneOf":[{"$ref":"#/components/schemas/PayoutIncomingDestinationExternalAccount"},{"$ref":"#/components/schemas/PayoutIncomingDestinationPaymentSource"},{"$ref":"#/components/schemas/PayoutIncomingDestinationBusinessAccount"},{"$ref":"#/components/schemas/PayoutIncomingDestinationUserDetermined"}],"discriminator":{"propertyName":"type","mapping":{"external_account":"#/components/schemas/PayoutIncomingDestinationExternalAccount","payment_source":"#/components/schemas/PayoutIncomingDestinationPaymentSource","business_account":"#/components/schemas/PayoutIncomingDestinationBusinessAccount","user_determined":"#/components/schemas/PayoutIncomingDestinationUserDetermined"}}},"PayoutIncomingSchemeSelectionInstantPreferred":{"title":"Instant Preferred","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Automatically select a payment scheme that supports instant payments based on currency and geography,\nwith a fallback to a non-instant scheme if instant payment is unavailable.\nThe `payout_executed` webhook will specify the actual scheme used.\nThis is optimal when slow settlement is not a concern. This is used by default if no `scheme_selection` is provided.\n","enum":["instant_preferred"]}}},"PayoutIncomingSchemeSelectionInstantOnly":{"title":"Instant Only","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Automatically select a payment scheme that supports instant payments based on currency and geography.\nThis is optimal when quick settlement is essential.\n","enum":["instant_only"]}}},"PayoutIncomingSchemeSelectionPreselected":{"title":"Preselected","type":"object","required":["type","scheme_id"],"properties":{"type":{"type":"string","description":"Specify","enum":["preselected"]},"scheme_id":{"type":"string","description":"Select a payment scheme compatible with the currency and geographic region to avoid payout failures after submission.\nThis helps with payouts by selecting the better-performing scheme between two similar options in a region, based on various criteria.\n","enum":["faster_payments_service","sepa_credit_transfer_instant","sepa_credit_transfer","polish_domestic_standard","polish_domestic_express"]}}},"PayoutIncomingSchemeSelection":{"oneOf":[{"$ref":"#/components/schemas/PayoutIncomingSchemeSelectionInstantPreferred"},{"$ref":"#/components/schemas/PayoutIncomingSchemeSelectionInstantOnly"},{"$ref":"#/components/schemas/PayoutIncomingSchemeSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"instant_preferred":"#/components/schemas/PayoutIncomingSchemeSelectionInstantPreferred","instant_only":"#/components/schemas/PayoutIncomingSchemeSelectionInstantOnly","preselected":"#/components/schemas/PayoutIncomingSchemeSelectionPreselected"}}},"PayoutIncomingUltimateCounterparty":{"oneOf":[{"$ref":"#/components/schemas/UltimateCounterpartyBusinessClient"}],"discriminator":{"propertyName":"type","mapping":{"business_client":"#/components/schemas/UltimateCounterpartyBusinessClient"}}},"PayoutIncomingSubmerchants":{"title":"Sub merchants","type":"object","description":"The details related to any applicable sub-merchants, for example a partner you are working with.","properties":{"ultimate_counterparty":{"$ref":"#/components/schemas/PayoutIncomingUltimateCounterparty"}}},"CreatePayout":{"type":"object","title":"Create payout","properties":{"merchant_account_id":{"$ref":"#/components/schemas/MerchantAccountId"},"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP","minimum":1},"currency":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"},"beneficiary":{"$ref":"#/components/schemas/PayoutIncomingDestination"},"scheme_selection":{"$ref":"#/components/schemas/PayoutIncomingSchemeSelection"},"sub_merchants":{"$ref":"#/components/schemas/PayoutIncomingSubmerchants"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["merchant_account_id","amount_in_minor","currency","beneficiary"]},"PayoutCreatedCommon":{"title":"Newly created payout","type":"object","required":["id"],"properties":{"id":{"type":"string","description":"ID of the payout","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"}}},"PayoutCreatedRegular":{"title":"Regular payout","allOf":[{"$ref":"#/components/schemas/PayoutCreatedCommon"}]},"PayoutCreatedUserDetermined":{"title":"User determined payout","allOf":[{"$ref":"#/components/schemas/PayoutCreatedCommon"},{"type":"object","properties":{"status":{"description":"Status of the created payout.\n\n🚧 Currently, this exists exclusively for `user_determined` payouts, and `authorization_required` is the only possible value;\nhowever, future standard payout scenarios may introduce additional statuses.\n","type":"string","enum":["authorization_required"]},"resource_token":{"type":"string","description":"A payout token in JWT format, with a limited scope that is authorized to be used with a single payout\n\nOnly available in payouts with `user_determined` beneficiary type.\n","format":"application/jwt"},"user":{"description":"Details on the user of the created payout.\n\nOnly available in payouts with `user_determined` beneficiary type.\n","$ref":"#/components/schemas/PaymentUser"}},"required":["status","resource_token","user"]}]},"CreatePayout-2":{"oneOf":[{"$ref":"#/components/schemas/PayoutCreatedRegular"},{"$ref":"#/components/schemas/PayoutCreatedUserDetermined"}]},"PayoutId":{"type":"string","description":"Unique ID for the Payout","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"},"PayoutDestinationExternalAccount":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","account_identifier","reference"],"properties":{"type":{"type":"string","description":"Type \"external_account\"","enum":["external_account"]},"reference":{"type":"string"},"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}}},"PayoutDestinationPaymentSource":{"title":"Payment Source","type":"object","required":["type","user_id","payment_source_id","reference","account_identifiers","account_holder_name"],"properties":{"type":{"type":"string","description":"Type \"payment_source\"","enum":["payment_source"]},"payment_source_id":{"type":"string","description":"ID of the external account which has become a payment source"},"user_id":{"type":"string","description":"ID of the owning user of the external account"},"reference":{"type":"string","description":"Reference for the payout"},"account_holder_name":{"type":"string","description":"The name of the account holder.\n"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}}},"PayoutDestinationBusinessAccount":{"title":"Business Account","type":"object","required":["type","account_holder_name","account_identifiers","reference"],"properties":{"type":{"type":"string","description":"Type \"business_account\"","enum":["business_account"]},"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}},"reference":{"type":"string"}}},"PayoutBeneficiaryVerification":{"type":"object","description":"Object that describes the verification checks that were request for the payout.","properties":{"verify_name":{"type":"boolean","description":"Whether to verify the account holder name. \n"},"transaction_search_criteria":{"$ref":"#/components/schemas/PayoutBeneficiaryVerificationTransactionSearchCriteria"}}},"PayoutDestinationUserDetermined":{"type":"object","title":"User Determined","description":"User determined beneficiary details","required":["type","reference","user"],"properties":{"type":{"type":"string","description":"Type \"user_determined\"","enum":["user_determined"]},"reference":{"description":"The reference for the payout, which displays in the beneficiary's bank statement.\n\nFor SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n\nFor FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,’+\\s#=!\"%&*<>;{@\\r\\n]*$`\n","type":"string"},"user":{"$ref":"#/components/schemas/PaymentUser"},"account_holder_name":{"description":"The name of the account holder.\n","type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}},"verification":{"$ref":"#/components/schemas/PayoutBeneficiaryVerification"}}},"PayoutDestination":{"oneOf":[{"$ref":"#/components/schemas/PayoutDestinationExternalAccount"},{"$ref":"#/components/schemas/PayoutDestinationPaymentSource"},{"$ref":"#/components/schemas/PayoutDestinationBusinessAccount"},{"$ref":"#/components/schemas/PayoutDestinationUserDetermined"}],"discriminator":{"propertyName":"type","mapping":{"external_account":"#/components/schemas/PayoutDestinationExternalAccount","payment_source":"#/components/schemas/PayoutDestinationPaymentSource","business_account":"#/components/schemas/PayoutDestinationBusinessAccount","user_determined":"#/components/schemas/PayoutDestinationUserDetermined"}}},"PaymentScheme":{"type":"string","enum":["faster_payments_service","sepa_credit_transfer","sepa_credit_transfer_instant","polish_domestic_standard","polish_domestic_express","norwegian_domestic_credit_transfer"]},"PayoutCommon":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PayoutId"},"merchant_account_id":{"$ref":"#/components/schemas/MerchantAccountId"},"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP","minimum":1},"currency":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"},"beneficiary":{"$ref":"#/components/schemas/PayoutDestination"},"metadata":{"$ref":"#/components/schemas/Metadata"},"scheme_id":{"description":"The id of the scheme used to execute the payout","$ref":"#/components/schemas/PaymentScheme"},"created_at":{"type":"string","description":"The date and time the payout was created at","format":"date-time"}},"required":["id","merchant_account_id","amount_in_minor","currency","beneficiary","created_at"]},"PayoutPending":{"title":"Pending","type":"object","description":"The payout has been created against TrueLayer's API but it has not yet been authorized and sent to the payment scheme for execution.\n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["pending"]}},"required":["status"]}]},"PayoutAuthorizationRequired":{"title":"Authorization required","type":"object","description":"The payout has been created against TrueLayer's API but it needs an action from the end user to proceed to next stages.\n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorization_required"]}},"required":["status"]}]},"PayoutAuthorizing":{"title":"Authorizing","type":"object","description":"The payout has been created against TrueLayer's API and the associated authorization flow in progress. \n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorizing"]}},"required":["status"]}]},"PayoutAuthorized":{"title":"Authorized","type":"object","description":"The payout has been authorized (i.e. there are enough funds) and\nit has been submitted to the payment scheme for execution.\n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorized"]}},"required":["status"]}]},"PayoutExecuted":{"title":"Executed","type":"object","description":"The payout was executed - the funds have left your merchant\naccount.\n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["executed"]},"executed_at":{"type":"string","description":"The date and time the payout transitioned to `executed`","format":"datetime"}},"required":["status","executed_at"]}]},"PayoutFailed":{"title":"Failed","type":"object","description":"The payout failed - the funds have not left your merchant account.\n","allOf":[{"$ref":"#/components/schemas/PayoutCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"executed_at":{"type":"string","description":"The date and time the payout transitioned to `executed`","format":"datetime"},"failed_at":{"type":"string","description":"The date and time the payout transitioned to `failed`","format":"datetime"},"failure_reason":{"$ref":"#/components/schemas/OutboundPaymentFailureReason"}},"required":["status","failed_at","failure_reason"]}]},"Payout":{"oneOf":[{"$ref":"#/components/schemas/PayoutPending"},{"$ref":"#/components/schemas/PayoutAuthorizationRequired"},{"$ref":"#/components/schemas/PayoutAuthorizing"},{"$ref":"#/components/schemas/PayoutAuthorized"},{"$ref":"#/components/schemas/PayoutExecuted"},{"$ref":"#/components/schemas/PayoutFailed"}],"discriminator":{"propertyName":"status","mapping":{"pending":"#/components/schemas/PayoutPending","authorization_required":"#/components/schemas/PayoutAuthorizationRequired","authorizing":"#/components/schemas/PayoutAuthorizing","authorized":"#/components/schemas/PayoutAuthorized","executed":"#/components/schemas/PayoutExecuted","failed":"#/components/schemas/PayoutFailed"}}},"PayoutAuthorizationFlowCreated":{"allOf":[{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["created"]}}}]},"PayoutAuthorizationFlowNextAction":{"oneOf":[{"$ref":"#/components/schemas/ActionSpecRedirect"}],"discriminator":{"propertyName":"type","mapping":{"redirect":"#/components/schemas/ActionSpecRedirect"}},"description":"The next action to be performed on the payout authorization flow\n"},"PayoutAuthorizationFlowStarted":{"type":"object","required":["status","actions"],"properties":{"status":{"enum":["authorizing"]},"actions":{"type":"object","description":"Object representing the next actions, if any. Present when the authorization flow is yet to be completed","required":["next"],"properties":{"next":{"$ref":"#/components/schemas/PayoutAuthorizationFlowNextAction"}}}}},"PayoutAuthorizationFlowCompleted":{"allOf":[{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["completed"]},"failure_reason":{"type":"string","enum":["account_not_valid","internal_error"],"description":"Possible failure reasons:\n- `account_not_valid` - Either none or more than one personal account have been connected\n- `internal_error` - An internal error happened\n"}}}]},"GetPayoutAuthorizationFlowResponse":{"oneOf":[{"$ref":"#/components/schemas/PayoutAuthorizationFlowCreated"},{"$ref":"#/components/schemas/PayoutAuthorizationFlowStarted"},{"$ref":"#/components/schemas/PayoutAuthorizationFlowCompleted"}],"discriminator":{"propertyName":"status","mapping":{"created":"#/components/schemas/PayoutAuthorizationFlowCreated","started":"#/components/schemas/PayoutAuthorizationFlowStarted","completed":"#/components/schemas/PayoutAuthorizationFlowCompleted"}}},"StartPayoutAuthorizationFlow":{"type":"object","description":"An object representing the request to start a authorization flow for a specific payout\n","required":["redirect"],"properties":{"redirect":{"type":"object","description":"Can the UI redirect the end user to a third-party page?\n\nFor most providers, payment authorization is achieved by redirecting the user to their chosen provider's page, where they can sign in with their credentials and approve the payment.\nThis field declares whether the UI is able to perform such a redirect.\n","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"During the authorization flow the end user might be redirected\nto another page (e.g. bank website, TrueLayer's Hosted Payment Page).\nThis URL determines where they will be redirected back once they completed\nthe flow on the third-party's website.\n\n`return_uri` must be one of the allowed `return_uri`s registered\nin TrueLayer's Console.\n","format":"url"}}}},"example":{"redirect":{"return_uri":"https://my-site.com/payout-return"}}},"StartPayoutAuthorizationFlowResponse":{"oneOf":[{"$ref":"#/components/schemas/PayoutAuthorizationFlowStarted"},{"$ref":"#/components/schemas/PayoutAuthorizationFlowCompleted"}],"discriminator":{"propertyName":"status","mapping":{"started":"#/components/schemas/PayoutAuthorizationFlowStarted","completed":"#/components/schemas/PayoutAuthorizationFlowCompleted"}}},"AvailableBalance":{"type":"integer","description":"The balance immediately available to perform payouts and transfers, expressed in the smallest denomination of the account's currency.\n\nThe available balance does also take into consideration transactions that are not yet in a final state.\n"},"CurrentBalance":{"type":"integer","description":"The current balance, expressed in the smallest denomination of the account's currency.\n\nThe current balance does not take into consideration transactions that are not yet in a final state.\n"},"MerchantAccount":{"type":"object","required":["id","currency","account_identifiers","available_balance_in_minor","current_balance_in_minor","account_holder_name"],"properties":{"id":{"$ref":"#/components/schemas/MerchantAccountId"},"currency":{"type":"string","description":"The ISO 4217 code of the currency associated with the merchant account.\n\nMerchant accounts can only hold funds in a single currency.\n","enum":["GBP","EUR","PLN"]},"account_identifiers":{"description":"The different identifiers you can use to route payments into this account\nover various payment schemes.\n\nThese identifiers can be used as beneficiary details if you need\nto deposit funds into your merchant account via manual bank\ntransfers.\n\nAll end users payments into your account should be authorized via\na payment with `merchant_account` as destination type.\n","type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}},"available_balance_in_minor":{"$ref":"#/components/schemas/AvailableBalance"},"current_balance_in_minor":{"$ref":"#/components/schemas/CurrentBalance"},"account_holder_name":{"type":"string","description":"The name of the account holder.\n\nIt must match your organisation's legal name.\n"}}},"ListMerchantAccounts":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MerchantAccount"}}}},"TransactionId":{"type":"string","description":"Unique ID for the Transaction"},"TransactionCommon":{"type":"object","required":["id","currency","amount_in_minor"],"properties":{"id":{"$ref":"#/components/schemas/TransactionId"},"currency":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"},"amount_in_minor":{"type":"integer","minimum":1}}},"TransactionPayinCommon":{"allOf":[{"$ref":"#/components/schemas/TransactionCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["settled"]},"settled_at":{"type":"string","description":"The date and time the transaction was settled","format":"datetime"}},"required":["status","settled_at"]}]},"TransactionMerchantAccountPayment":{"title":"Merchant Account Payment","description":"Payment into the merchant account initiated by a TrueLayer Payment","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["merchant_account_payment"]}},"required":["type"]},{"$ref":"#/components/schemas/TransactionPayinCommon"},{"type":"object","properties":{"payment_source":{"type":"object","$ref":"#/components/schemas/SettledPaymentSource"},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["payment_source","payment_id"]}]},"ReturnForIdentified":{"title":"Identified","type":"object","properties":{"type":{"type":"string","description":"This external payment returned an outbound transaction.\n","enum":["identified"]},"returned_id":{"type":"string","description":"Unique ID for the outbound transaction that returned","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"}},"required":["type","returned_id"]},"ReturnForUnknown":{"title":"Unknown","type":"object","properties":{"type":{"type":"string","description":"This external payment returned an unknown outbound transaction.\n","enum":["unknown"]}},"required":["type"]},"ReturnFor":{"title":"Return for","type":"object","oneOf":[{"$ref":"#/components/schemas/ReturnForIdentified"},{"$ref":"#/components/schemas/ReturnForUnknown"}],"discriminator":{"propertyName":"type","mapping":{"identified":"#/components/schemas/ReturnForIdentified","unknown":"#/components/schemas/ReturnForUnknown"}}},"TransactionExternalPayment":{"title":"External Payment","description":"Payment into the merchant account _not_ initiated by a TrueLayer Payment","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["external_payment"]}},"required":["type"]},{"$ref":"#/components/schemas/TransactionPayinCommon"},{"type":"object","properties":{"remitter":{"type":"object","properties":{"account_holder_name":{"description":"The name of the external account holder.","type":"string"},"reference":{"type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}},"required":["account_holder_name","account_identifiers","reference"]},"return_for":{"$ref":"#/components/schemas/ReturnFor"}},"required":["remitter"]}]},"TransactionPayoutDestinationUserDetermined":{"type":"object","title":"User Determined","description":"User determined beneficiary details","required":["type","reference"],"properties":{"type":{"type":"string","description":"Type \"user_determined\"","enum":["user_determined"]},"reference":{"description":"The reference for the payout, which displays in the beneficiary's bank statement.\n\nFor SEPA payments, the maximum length is **140 characters**. The format must respect the requirements specified [here](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n\nFor FPS payments, the maximum length is **18 characters**. The format must respect this regex: `^[a-zA-Z0-9\\/\\-?:().,’+\\s#=!\"%&*<>;{@\\r\\n]*$`\n","type":"string"},"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}}}},"TransactionPayoutDestination":{"oneOf":[{"$ref":"#/components/schemas/PayoutDestinationExternalAccount"},{"$ref":"#/components/schemas/PayoutDestinationPaymentSource"},{"$ref":"#/components/schemas/PayoutDestinationBusinessAccount"},{"$ref":"#/components/schemas/TransactionPayoutDestinationUserDetermined"}],"discriminator":{"propertyName":"type","mapping":{"external_account":"#/components/schemas/PayoutDestinationExternalAccount","payment_source":"#/components/schemas/PayoutDestinationPaymentSource","business_account":"#/components/schemas/PayoutDestinationBusinessAccount","user_determined":"#/components/schemas/TransactionPayoutDestinationUserDetermined"}}},"TransactionPayoutContextCode":{"type":"string","enum":["withdrawal","service_payment","internal"]},"TransactionPayoutExecuted":{"title":"Executed Payout","description":"Payment out of the merchant account","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["payout"]}},"required":["type"]},{"$ref":"#/components/schemas/TransactionCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["executed"]},"created_at":{"type":"string","description":"The date and time the transaction was created","format":"datetime"},"executed_at":{"type":"string","description":"The date and time the transaction was executed","format":"datetime"},"beneficiary":{"$ref":"#/components/schemas/TransactionPayoutDestination"},"context_code":{"$ref":"#/components/schemas/TransactionPayoutContextCode"},"payout_id":{"$ref":"#/components/schemas/PayoutId"},"returned_by":{"type":"string","description":"Unique ID for the external payment that returned this payout","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"},"scheme_id":{"description":"The id of the scheme used to execute the payout","$ref":"#/components/schemas/PaymentScheme"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["status","created_at","executed_at","beneficiary","context_code","payout_id"]}]},"TransactionRefund":{"title":"Refund","description":"Payment refund out of the merchant account","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["refund"]}},"required":["type"]},{"$ref":"#/components/schemas/TransactionCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["executed"]},"created_at":{"type":"string","description":"The date and time the transaction was created","format":"datetime"},"executed_at":{"type":"string","description":"The date and time the transaction was executed, provided in status \"executed\"","format":"datetime"},"beneficiary":{"$ref":"#/components/schemas/PayoutDestinationPaymentSource"},"context_code":{"$ref":"#/components/schemas/TransactionPayoutContextCode"},"refund_id":{"$ref":"#/components/schemas/PaymentRefundId"},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"returned_by":{"type":"string","description":"Unique ID for the external payment that returned this refund","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"},"scheme_id":{"description":"The id of the scheme used to execute the payout","$ref":"#/components/schemas/PaymentScheme"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["status","created_at","beneficiary","context_code","refund_id","payment_id"]}]},"Transaction":{"oneOf":[{"$ref":"#/components/schemas/TransactionMerchantAccountPayment"},{"$ref":"#/components/schemas/TransactionExternalPayment"},{"$ref":"#/components/schemas/TransactionPayoutExecuted"},{"$ref":"#/components/schemas/TransactionRefund"}]},"GetTransactions":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"SweepingFrequency":{"type":"string","description":"How often the available balance will be checked for sweeping.","enum":["hourly","every_3_hours","every_6_hours","every_12_hours","daily","weekly","fortnightly"]},"SweepingSettingsConfigured":{"type":"object","properties":{"max_amount_in_minor":{"type":"integer","description":"A 'cent' value representing the max desired amount,\nabove which funds will be automatically withdrawn.\neg 100 == 1GBP\n"},"currency":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"},"frequency":{"$ref":"#/components/schemas/SweepingFrequency"},"destination":{"oneOf":[{"$ref":"#/components/schemas/AccountIdentifierIban"}],"discriminator":{"propertyName":"type","mapping":{"iban":"#/components/schemas/AccountIdentifierIban"}}}},"required":["max_amount_in_minor","currency","frequency","destination"]},"SweepingSettingsRequested":{"type":"object","properties":{"max_amount_in_minor":{"type":"integer","description":"A 'cent' value representing the max desired amount,\nabove which funds will be automatically withdrawn.\neg 100 == 1GBP\n"},"frequency":{"description":"How often the available balance will be checked for sweeping,\ndefaults to `daily`.\n","$ref":"#/components/schemas/SweepingFrequency"}},"required":["max_amount_in_minor"]},"UserPaymentSources":{"title":"UserPaymentSources","type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SettledPaymentSource"},"uniqueItems":true,"minItems":0}}},"MandateId":{"type":"string","description":"Unique ID for the mandate","example":"be6db706-68f1-4e9c-ab09-b83d8e3ea60d"},"GetMandateBeneficiaryReference":{"title":"Reference","type":"string","description":"The auto-generated reference for the mandate. Read more about references [here](https://docs.truelayer.com/docs/recurring-payment-references-reconciliation)"},"GetMandateDestinationMerchantAccount":{"type":"object","title":"Merchant Account","description":"The identifier for a TrueLayer's merchant account.","required":["type","merchant_account_id"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["merchant_account"]},"merchant_account_id":{"description":"The unique identifier of a TrueLayer merchant account.\n","$ref":"#/components/schemas/MerchantAccountId"},"account_holder_name":{"description":"The name of the beneficiary, which displays in the remitter's bank statement.\nIf unspecified, the API uses the account owner name associated with the selected merchant account.\n","type":"string"},"reference":{"$ref":"#/components/schemas/GetMandateBeneficiaryReference"}}},"GetMandateDestinationExternalAccount":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","account_identifier"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["external_account"]},"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"},"reference":{"$ref":"#/components/schemas/GetMandateBeneficiaryReference"}}},"GetVRPPaymentDestination":{"oneOf":[{"$ref":"#/components/schemas/GetMandateDestinationMerchantAccount"},{"$ref":"#/components/schemas/GetMandateDestinationExternalAccount"}],"discriminator":{"propertyName":"type","mapping":{"merchant_account":"#/components/schemas/GetMandateDestinationMerchantAccount","external_account":"#/components/schemas/GetMandateDestinationExternalAccount"}}},"MandateProviderSelectionUserSelectedResponse":{"title":"User selected","type":"object","description":"Indicates that the provider is to be selected from a collection","required":["type"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["user_selected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment. Will be populated when the provider selection has been submitted.","example":["eg-provider"]},"filter":{"$ref":"#/components/schemas/ProviderFilter"}}},"MandateProviderSelectionPreselected":{"title":"Preselected","type":"object","description":"Preselected provider. Indicates that the provider for this payment is preselected.","required":["type","provider_id"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["preselected"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment.","example":["eg-provider"]},"remitter":{"$ref":"#/components/schemas/Remitter"}}},"MandateProviderSelectionResponse":{"title":"Provider Selection","type":"object","description":"Provider Selection","oneOf":[{"$ref":"#/components/schemas/MandateProviderSelectionUserSelectedResponse"},{"$ref":"#/components/schemas/MandateProviderSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"user_selected":"#/components/schemas/MandateProviderSelectionUserSelectedResponse","preselected":"#/components/schemas/MandateProviderSelectionPreselected"}}},"VRPPeriodicLimit":{"title":"Periodic Limit","type":"object","required":["period_alignment","maximum_amount"],"properties":{"maximum_amount":{"type":"integer","description":"A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period.\n\n`maximum_amount` must be greater or equal to `maximum_individual_amount` specified on the `constraints` object if `maximum_individual_amount` has been specified.\n","minimum":1},"period_alignment":{"type":"string","enum":["consent","calendar"],"description":"Specifies whether the period starts on the date of consent creation or lines up with a calendar.\n\nIf the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days.\n"}}},"VRPConstraints":{"title":"Constraints","description":"Sets the limits for the payments that can be created by the mandate.\n\nIf a payment is attempted that doesn't fit within these constraints it will fail.\n\nThese constraints are considered only for VRP mandates (not direct debit).\n","required":["maximum_individual_amount","periodic_limits"],"properties":{"valid_from":{"type":"string","format":"datetime","example":"2022-01-01T00:00:00.000Z","description":"Start date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ`\n"},"valid_to":{"type":"string","format":"datetime","example":"2022-12-31T23:59:59.999Z","description":"End date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ`\n"},"maximum_individual_amount":{"type":"integer","description":"A 'cent' value representing the maximum amount that can be specified in a payment instruction","minimum":1,"maximum":100000000},"periodic_limits":{"type":"object","title":"Periodic Limits","description":"The limits for the payments that can be created by the mandate within a specified time period.\n\nAt least one periodic limit must be provided upon mandate creation.\n","properties":{"day":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within a day"}]},"week":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within a week"}]},"fortnight":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within a fortnight\n\nOnly supports `period_alignment` of `consent`.\n"}]},"month":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within a month"}]},"half_year":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within 6 months"}]},"year":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodicLimit"},{"description":"Limit for payments made within a year"}]}}}}},"GetVRPMandateCommonWithUserDetails":{"allOf":[{"type":"object","required":["id","currency","source","created_at","constraints","beneficiary","reference","provider_selection"],"properties":{"id":{"$ref":"#/components/schemas/MandateId"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"beneficiary":{"$ref":"#/components/schemas/GetVRPPaymentDestination"},"reference":{"type":"string","deprecated":true,"description":"Reference set on the mandate. This field is deprecated. Please use the `statement_reference` field instead."},"statement_reference":{"type":"string","description":"Reference set on the mandate."},"provider_selection":{"$ref":"#/components/schemas/MandateProviderSelectionResponse"},"user":{"$ref":"#/components/schemas/PaymentUser"},"created_at":{"type":"string","description":"The date and time the mandate was created at.","format":"datetime"},"constraints":{"$ref":"#/components/schemas/VRPConstraints"},"metadata":{"$ref":"#/components/schemas/Metadata"},"sub_merchants":{"$ref":"#/components/schemas/PaymentSubMerchants"}}}]},"GetVRPMandateAuthorizationRequiredWithUserDetails":{"title":"Authorization Required","description":"A mandate yet to be authorized.\n\nThis is the first status for a mandate that requires further actions\nto be authorized.\n","allOf":[{"$ref":"#/components/schemas/GetVRPMandateCommonWithUserDetails"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authorization_required"]}}}]},"ActionSpecWaitForOutcome-2":{"type":"object","title":"Wait for Outcome","description":"Indication that there are currently no actions to perform.\n","properties":{"type":{"type":"string","enum":["wait"]},"display_message":{"$ref":"#/components/schemas/DisplayText","description":"An optional message to be displayed to the end user while they are waiting."},"async_outcome":{"type":"object","description":"It indicates that the user flow can continue and you can check the mandate status later. You don't need to wait synchronously for the status to change at this point."}},"required":["type"]},"ActionSpecConsent-2":{"type":"object","title":"Consent","properties":{"type":{"type":"string","enum":["consent"]},"subsequent_action_hint":{"type":"string","enum":["redirect"]}},"required":["subsequent_action_hint","type"]},"MandateNextAction":{"oneOf":[{"$ref":"#/components/schemas/ActionSpecProviderSelection"},{"$ref":"#/components/schemas/ActionSpecRedirect"},{"$ref":"#/components/schemas/ActionSpecWaitForOutcome-2"},{"$ref":"#/components/schemas/ActionSpecConsent-2"}],"discriminator":{"propertyName":"type","mapping":{"provider_selection":"#/components/schemas/ActionSpecProviderSelection","redirect":"#/components/schemas/ActionSpecRedirect","wait":"#/components/schemas/ActionSpecWaitForOutcome-2","consent":"#/components/schemas/ActionSpecConsent-2"}},"description":"The next action can be performed via `POST /v3/mandate/{id}/authorization_flow/action/{action_name}` -\ncheck its documentation for relevant examples.\n"},"MandateAuthorizationFlow":{"type":"object","title":"Authorization Flow","description":"Contains information regarding the nature and the state of the authorization flow\n","required":["actions"],"properties":{"actions":{"type":"object","required":["next"],"properties":{"next":{"$ref":"#/components/schemas/MandateNextAction"}}}}},"MandateAuthorizationFlowConfiguration":{"type":"object","title":"Configuration","required":["provider_selection","redirect"],"properties":{"provider_selection":{"type":"object","description":"Can the UI render a provider selection screen?\n\nConfiguration options are available to constrain which providers should be shown.\n"},"redirect":{"type":"object","description":"Can the UI redirect the end user to a third-party page?\n\nConfiguration options are available to constrain if TrueLayer's Hosted\nPayment Page should be leveraged.\n","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"During the authorization flow the end user might be redirected\nto another page (e.g. bank website, TrueLayer's Hosted Payment Page).\nThis URL determines where they will be redirected back once they completed\nthe flow on the third-party's website.\n\nThis field is optional - if left unspecified, the end user will be redirected\nback to the default URI specified in your client settings in TrueLayer's Console.\n\n`return_uri`, if specified, must be one of the allowed `return_uri`s registered\nin TrueLayer's Console.\n","format":"url"}}}}},"GetVRPMandateAuthorizingWithUserDetails":{"title":"Authorizing","allOf":[{"$ref":"#/components/schemas/GetVRPMandateCommonWithUserDetails"},{"type":"object","required":["status","authorization_flow"],"properties":{"status":{"type":"string","enum":["authorizing"]},"authorization_flow":{"allOf":[{"$ref":"#/components/schemas/MandateAuthorizationFlow"},{"type":"object","properties":{"configuration":{"$ref":"#/components/schemas/MandateAuthorizationFlowConfiguration"}}}]}}}]},"MandateAuthorizationFlowFrozen":{"type":"object","title":"Authorization Flow","description":"Information about the authorization flow the mandate went through.\n\nIf the mandate transitioned immediately to `authorized` or `failed`,\nthis field will be null.\n","required":["configuration"],"properties":{"configuration":{"$ref":"#/components/schemas/MandateAuthorizationFlowConfiguration"}}},"VRPPaymentRemitter":{"type":"object","title":"Remitter Account","description":"The routing information for the remitter bank account.","required":["account_holder_name","account_identifier"],"properties":{"account_holder_name":{"description":"The name of the remitter account holder.\n","type":"string"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"}}},"GetVRPMandateAuthorizedWithUserDetails":{"title":"Authorized","allOf":[{"$ref":"#/components/schemas/GetVRPMandateCommonWithUserDetails"},{"type":"object","required":["status","authorization_flow"],"properties":{"status":{"type":"string","enum":["authorized"]},"authorized_at":{"type":"string","description":"The date and time the mandate was authorized at","format":"datetime"},"authorization_flow":{"$ref":"#/components/schemas/MandateAuthorizationFlowFrozen"},"remitter":{"$ref":"#/components/schemas/VRPPaymentRemitter"}}}]},"MandateFailureStage":{"type":"string","enum":["authorization_required","authorized","authorizing","revoked"],"description":"The status the mandate was in when it failed.\n","example":"authorizing"},"MandateFailureReason":{"type":"string","description":"A readable detail for why the mandate failed.\nExample values to expect:\n- `authorization_failed`\n- `provider_error`\n- `provider_rejected`\n- `internal_server_error`\n- `invalid_sort_code`\n- `invalid_request`\n- `expired`\n- `unknown_error`\n","example":"authorization_failed"},"GetVRPMandateFailedWithUserDetails":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/GetVRPMandateCommonWithUserDetails"},{"type":"object","required":["status","failure_stage","failure_reason"],"properties":{"status":{"type":"string","enum":["failed"]},"failed_at":{"type":"string","description":"The date and time the mandate authorization was failed at","format":"datetime"},"failure_stage":{"$ref":"#/components/schemas/MandateFailureStage"},"failure_reason":{"$ref":"#/components/schemas/MandateFailureReason"},"authorization_flow":{"$ref":"#/components/schemas/MandateAuthorizationFlowFrozen"}}}]},"RevocationSource":{"type":"string","description":"Source for the revocation","enum":["client","provider"]},"GetVRPMandateRevokedWithUserDetails":{"title":"Revoked","allOf":[{"$ref":"#/components/schemas/GetVRPMandateCommonWithUserDetails"},{"type":"object","required":["status","revocation_source","authorization_flow"],"properties":{"status":{"type":"string","enum":["revoked"]},"revocation_source":{"$ref":"#/components/schemas/RevocationSource"},"authorization_flow":{"$ref":"#/components/schemas/MandateAuthorizationFlowFrozen"},"authorized_at":{"type":"string","description":"The date and time the mandate was authorized at","format":"datetime"},"revoked_at":{"type":"string","description":"The date and time the mandate was revoked at","format":"datetime"}}}]},"GetSweepingMandate":{"title":"Sweeping VRP mandate","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["sweeping"]}}},{"oneOf":[{"$ref":"#/components/schemas/GetVRPMandateAuthorizationRequiredWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateAuthorizingWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateAuthorizedWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateFailedWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateRevokedWithUserDetails"}],"discriminator":{"propertyName":"status"}}]},"GetCommercialMandate":{"title":"Commercial VRP mandate","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["commercial"]}}},{"oneOf":[{"$ref":"#/components/schemas/GetVRPMandateAuthorizationRequiredWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateAuthorizingWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateAuthorizedWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateFailedWithUserDetails"},{"$ref":"#/components/schemas/GetVRPMandateRevokedWithUserDetails"}],"discriminator":{"propertyName":"status"}}]},"GetDDRemitter":{"title":"Direct Debit Remitter","description":"Details of the individual for whom the DD is being created.","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["preselected"]}}},{"$ref":"#/components/schemas/Remitter"}]},"MandateDestinationMerchantAccount":{"type":"object","title":"Merchant Account","description":"The identifier for a TrueLayer's merchant account.","required":["type","merchant_account_id"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["merchant_account"]},"merchant_account_id":{"description":"The unique identifier of a TrueLayer merchant account.\n","$ref":"#/components/schemas/MerchantAccountId"},"account_holder_name":{"description":"The name of the beneficiary, which displays in the remitter's bank statement.\nIf unspecified, the API uses the account owner name associated with the selected merchant account.\n","type":"string"}}},"DDBeneficiary":{"type":"object","description":"The details of the account that will be receiving the payments.","oneOf":[{"$ref":"#/components/schemas/MandateDestinationMerchantAccount"}],"discriminator":{"propertyName":"type","mapping":{"merchant_account":"#/components/schemas/MandateDestinationMerchantAccount"}}},"GetDDMandateCommon":{"allOf":[{"type":"object","required":["id","currency","remitter","beneficiary","created_at"],"properties":{"id":{"$ref":"#/components/schemas/MandateId"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"remitter":{"$ref":"#/components/schemas/GetDDRemitter"},"beneficiary":{"$ref":"#/components/schemas/DDBeneficiary"},"user":{"$ref":"#/components/schemas/PaymentUser"},"created_at":{"type":"string","description":"The date and time the mandate was created at.","format":"datetime"},"metadata":{"$ref":"#/components/schemas/Metadata"},"sub_merchants":{"$ref":"#/components/schemas/PaymentSubMerchants"}}}]},"GetDDMandateAuthorizationRequired":{"title":"Authorization Required","description":"A mandate yet to be authorized.\n\nThis is the first status for a mandate that requires further actions to be authorized.\n","allOf":[{"$ref":"#/components/schemas/GetDDMandateCommon"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authorization_required"]}}}]},"GetDDMandateAuthorizing":{"title":"Authorizing","allOf":[{"$ref":"#/components/schemas/GetDDMandateCommon"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["authorizing"]},"authorization_flow":{"allOf":[{"$ref":"#/components/schemas/MandateAuthorizationFlow"},{"type":"object","properties":{"configuration":{"$ref":"#/components/schemas/MandateAuthorizationFlowConfiguration"}}}]}}}]},"GetDDMandateAuthorized":{"title":"Authorized","allOf":[{"$ref":"#/components/schemas/GetDDMandateCommon"},{"type":"object","required":["status","authorized_at","statement_reference"],"properties":{"status":{"type":"string","enum":["authorized"]},"statement_reference":{"type":"string","description":"Reference set on the mandate."},"authorized_at":{"type":"string","description":"The date and time the mandate was authorized at.","format":"datetime"}}}]},"GetDDMandateFailed":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/GetDDMandateCommon"},{"type":"object","required":["status","failed_at","failure_stage","failure_reason"],"properties":{"status":{"type":"string","enum":["failed"]},"failed_at":{"type":"string","description":"The date and time the mandate authorization failed at.","format":"datetime"},"failure_stage":{"$ref":"#/components/schemas/MandateFailureStage"},"failure_reason":{"$ref":"#/components/schemas/MandateFailureReason"}}}]},"GetDDMandateRevoked":{"title":"Revoked","allOf":[{"$ref":"#/components/schemas/GetDDMandateCommon"},{"type":"object","required":["status","revocation_source","authorized_at","revoked_at","statement_reference"],"properties":{"status":{"type":"string","enum":["revoked"]},"statement_reference":{"type":"string","description":"Reference set on the mandate."},"revocation_source":{"$ref":"#/components/schemas/RevocationSource"},"authorized_at":{"type":"string","description":"The date and time the mandate was authorized at.","format":"datetime"},"revoked_at":{"type":"string","description":"The date and time the mandate was revoked at.","format":"datetime"},"revocation_reason":{"type":"string","description":"The reason that the mandate was revoked."}}}]},"GetDDMandate":{"title":"Direct Debit mandate","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["direct_debit"]}}},{"oneOf":[{"$ref":"#/components/schemas/GetDDMandateAuthorizationRequired"},{"$ref":"#/components/schemas/GetDDMandateAuthorizing"},{"$ref":"#/components/schemas/GetDDMandateAuthorized"},{"$ref":"#/components/schemas/GetDDMandateFailed"},{"$ref":"#/components/schemas/GetDDMandateRevoked"}],"discriminator":{"propertyName":"status"}}]},"ListMandates":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/GetSweepingMandate"},{"$ref":"#/components/schemas/GetCommercialMandate"},{"$ref":"#/components/schemas/GetDDMandate"}]}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"MandateProviderSelectionUserSelected":{"title":"User selected","type":"object","description":"Indicates that the provider is to be selected from a collection","required":["type"],"properties":{"type":{"type":"string","description":"The type of provider.","enum":["user_selected"]},"filter":{"$ref":"#/components/schemas/ProviderFilter"}}},"MandateProviderSelection":{"title":"Provider Selection","type":"object","description":"Provider Selection","oneOf":[{"$ref":"#/components/schemas/MandateProviderSelectionUserSelected"},{"$ref":"#/components/schemas/MandateProviderSelectionPreselected"}],"discriminator":{"propertyName":"type","mapping":{"user_selected":"#/components/schemas/MandateProviderSelectionUserSelected","preselected":"#/components/schemas/MandateProviderSelectionPreselected"}}},"MandateDestinationExternalAccount":{"type":"object","title":"External Account","description":"The routing information for an external bank account.","required":["type","account_holder_name","account_identifier"],"properties":{"type":{"description":"The type of destination.","type":"string","enum":["external_account"]},"account_holder_name":{"description":"The name of the external account holder. This should not be more than 18 characters and shouldn’t contain [special characters](https://docs.truelayer.com/docs/character-limitations-in-payments#special-characters)\n","type":"string"},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier"}}},"VRPPaymentDestination":{"oneOf":[{"$ref":"#/components/schemas/MandateDestinationMerchantAccount"},{"$ref":"#/components/schemas/MandateDestinationExternalAccount"}],"discriminator":{"propertyName":"type","mapping":{"merchant_account":"#/components/schemas/MandateDestinationMerchantAccount","external_account":"#/components/schemas/MandateDestinationExternalAccount"}}},"MandateVRPSweeping":{"title":"VRP Sweeping","required":["type","beneficiary","provider_selection"],"properties":{"type":{"type":"string","description":"The type of VRP mandate that will be created.\n","enum":["sweeping"]},"provider_selection":{"$ref":"#/components/schemas/MandateProviderSelection"},"beneficiary":{"$ref":"#/components/schemas/VRPPaymentDestination"},"reference":{"description":"A custom reference for the mandate, available for regulated customers only.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$`.\nIf not specified, one is automatically set to be the clients name, adjusted as needed.\nThis field is deprecated. Please use the `statement_reference` field instead.\n","type":"string","deprecated":true,"maxLength":18,"example":"mandate-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$"},"statement_reference":{"description":"A custom reference for the mandate, available for regulated customers only.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$`.\nIf not specified, one is automatically set to be the clients name, adjusted as needed.\n","type":"string","maxLength":18,"example":"mandate-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$"}}},"MandateVRPCommercial":{"title":"VRP Commercial","required":["type","beneficiary","provider_selection"],"properties":{"type":{"type":"string","description":"The type of VRP mandate that will be created.\n","enum":["commercial"]},"provider_selection":{"$ref":"#/components/schemas/MandateProviderSelection"},"beneficiary":{"$ref":"#/components/schemas/VRPPaymentDestination"},"reference":{"description":"A custom reference for the mandate, available for regulated customers only.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$`.\nIf not specified, one is automatically set to be the clients name, adjusted as needed.\nThis field is deprecated. Please use the `statement_reference` field instead.\n","type":"string","deprecated":true,"maxLength":18,"example":"mandate-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$"},"statement_reference":{"description":"A custom reference for the mandate, available for regulated customers only.\npattern: `^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$`.\nIf not specified, one is automatically set to be the clients name, adjusted as needed.\n","type":"string","maxLength":18,"example":"mandate-ref","pattern":"^[a-zA-Z0-9-:()\\.,'\\+ \\?\\/]{1,18}$"}}},"DDPreselectedRemitter":{"title":"Preselected Remitter","allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["preselected"]},"address":{"$ref":"#/components/schemas/Address"}}},{"$ref":"#/components/schemas/Remitter","required":["type"]}]},"DDInitialPayment":{"title":"Initial Payment","type":"object","required":["amount_in_minor"],"properties":{"amount_in_minor":{"type":"integer","description":"A 'cent' value representing the amount. eg 100 == 1GBP or 100 = 1EUR","minimum":1,"example":1}}},"DDPaymentSourceProvidedRemitter":{"title":"Payment Source Provided Remitter","type":"object","properties":{"type":{"type":"string","enum":["payment_source_provided"]},"initial_payment":{"$ref":"#/components/schemas/DDInitialPayment"},"provider_selection":{"$ref":"#/components/schemas/BankTransferProviderSelection"}},"required":["type","provider_selection"]},"CreateDDRemitter":{"title":"Direct Debit Remitter","type":"object","oneOf":[{"$ref":"#/components/schemas/DDPreselectedRemitter"},{"$ref":"#/components/schemas/DDPaymentSourceProvidedRemitter"}],"discriminator":{"propertyName":"type","mapping":{"preselected":"#/components/schemas/DDPreselectedRemitter","payment_source_provided":"#/components/schemas/DDPaymentSourceProvidedRemitter"}}},"MandateDirectDebit":{"title":"Direct Debit","required":["type","remitter","beneficiary"],"properties":{"type":{"type":"string","description":"The type of mandate that will be created.\n\n> 📘\n>\n> Direct debits are in beta. Please contact us to learn more.\n","enum":["direct_debit"]},"remitter":{"$ref":"#/components/schemas/CreateDDRemitter"},"beneficiary":{"$ref":"#/components/schemas/DDBeneficiary"}}},"Mandate":{"title":"Mandate","oneOf":[{"$ref":"#/components/schemas/MandateVRPSweeping"},{"$ref":"#/components/schemas/MandateVRPCommercial"},{"$ref":"#/components/schemas/MandateDirectDebit"}],"discriminator":{"propertyName":"type","mapping":{"sweeping":"#/components/schemas/MandateVRPSweeping","commercial":"#/components/schemas/MandateVRPCommercial","direct_debit":"#/components/schemas/MandateDirectDebit"}}},"CreateMandate":{"title":"CreateMandate","allOf":[{"type":"object","required":["mandate","currency","user"],"properties":{"mandate":{"$ref":"#/components/schemas/Mandate"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"user":{"$ref":"#/components/schemas/PaymentUserCreate"},"constraints":{"$ref":"#/components/schemas/VRPConstraints"},"metadata":{"$ref":"#/components/schemas/Metadata"},"related_products":{"$ref":"#/components/schemas/RelatedProducts"},"sub_merchants":{"$ref":"#/components/schemas/PaymentSubMerchants"}}}]},"MandateCreatedCommon":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MandateId"},"user":{"type":"object","required":["id"],"description":"Details on the user of the created mandate.\n\nIf you didn't pass the `user_id` in the request body when you created the mandate, an ID is generated and returned in this response.\n","properties":{"id":{"type":"string","description":"ID of the user","example":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941"}}}},"required":["id","user"]},"MandateCreatedAuthorizationRequired":{"title":"Authorization Required","allOf":[{"$ref":"#/components/schemas/MandateCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorization_required"]},"resource_token":{"type":"string","description":"Token to use with `/mandate` endpoints.\n\nIt can be safely shared with a front end channel.\n"}},"required":["status","resource_token"]}]},"MandateCreatedAuthorizing":{"title":"Authorizing","allOf":[{"$ref":"#/components/schemas/MandateCreatedCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["authorizing"]}},"required":["status"]}]},"MandateCreated":{"oneOf":[{"$ref":"#/components/schemas/MandateCreatedAuthorizationRequired"},{"$ref":"#/components/schemas/MandateCreatedAuthorizing"}],"discriminator":{"propertyName":"status","mapping":{"authorization_required":"#/components/schemas/MandateCreatedAuthorizationRequired","authorizing":"#/components/schemas/MandateCreatedAuthorizing"}}},"GetMandate":{"oneOf":[{"$ref":"#/components/schemas/GetSweepingMandate"},{"$ref":"#/components/schemas/GetCommercialMandate"},{"$ref":"#/components/schemas/GetDDMandate"}]},"StartMandateAuthorizationFlow":{"type":"object","properties":{"provider_selection":{"type":"object","description":"Can the UI render a provider selection screen?\n"},"redirect":{"type":"object","description":"Can the UI redirect the end user to a third-party page?\n\nConfiguration options are available to constrain if TrueLayer's Hosted\nPayment Page should be leveraged.\n","required":["return_uri"],"properties":{"return_uri":{"type":"string","description":"During the authorization flow the end user might be redirected\nto another page (e.g. bank website, TrueLayer's Hosted Payment Page).\nThis URL determines where they will be redirected back once they completed\nthe flow on the third-party's website.\n\n`return_uri` must be one of the allowed `return_uri`s registered\nin TrueLayer's Console.\n","format":"url"}}},"consent":{"type":"object","description":"Can the UI capture the user's consent?\n\nThis field declares whether the UI supports the `consent` action, which is used to explicitly capture the end user's consent for initiating the payment.\nIf it is omitted, the flow will continue without a `consent` action.\n"}},"required":["provider_selection","redirect"],"example":{"provider_selection":{},"redirect":{"return_uri":"https://my-site.com/mandate-return"}}},"MandateAuthorizationStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"discriminator":{"propertyName":"status"}},"MandateAuthorizationFlowAuthorizing":{"allOf":[{"$ref":"#/components/schemas/MandateAuthorizationStatus"},{"type":"object","required":["authorization_flow"],"properties":{"status":{"enum":["authorizing"]},"authorization_flow":{"$ref":"#/components/schemas/MandateAuthorizationFlow"}}}]},"MandateAuthorizationFailureStage":{"type":"string","enum":["authorization_required","authorizing","authorized"],"description":"The status the mandate was in when it failed.\n","example":"authorizing"},"MandateAuthorizationFlowAuthorizationFailed":{"allOf":[{"$ref":"#/components/schemas/MandateAuthorizationStatus"},{"type":"object","required":["failure_stage","failure_reason","status"],"properties":{"status":{"enum":["failed"]},"failure_stage":{"$ref":"#/components/schemas/MandateAuthorizationFailureStage"},"failure_reason":{"$ref":"#/components/schemas/MandateFailureReason"}}}]},"StartMandateAuthorizationFlowResponse":{"oneOf":[{"$ref":"#/components/schemas/MandateAuthorizationFlowAuthorizing"},{"$ref":"#/components/schemas/MandateAuthorizationFlowAuthorizationFailed"}],"discriminator":{"propertyName":"status","mapping":{"authorizing":"#/components/schemas/MandateAuthorizationFlowAuthorizing","failed":"#/components/schemas/MandateAuthorizationFlowAuthorizationFailed"}}},"MandateProviderSelectionAction":{"oneOf":[{"$ref":"#/components/schemas/MandateAuthorizationFlowAuthorizing"},{"$ref":"#/components/schemas/MandateAuthorizationFlowAuthorizationFailed"}],"discriminator":{"propertyName":"status","mapping":{"authorizing":"#/components/schemas/MandateAuthorizationFlowAuthorizing","failed":"#/components/schemas/MandateAuthorizationFlowAuthorizationFailed"}}},"ConfirmationOfFunds":{"title":"Confirmation of funds","type":"object","required":["confirmed","confirmed_at"],"properties":{"confirmed":{"description":"Whether the funds are confirmed","type":"boolean"},"confirmed_at":{"type":"string","description":"The date and time the funds were confirmed at","format":"datetime"}}},"VRPPeriodState":{"title":"Period State","type":"object","required":["period_alignment","maximum_available_amount","current_amount","start_date","end_date"],"properties":{"period_alignment":{"type":"string","enum":["consent","calendar"],"description":"Specifies whether the period starts on the date of consent creation or lines up with a calendar.\n\nIf the `period_alignment` is `calendar`, the limit is pro-rated in the first period to the remaining number of days.\n"},"maximum_available_amount":{"type":"integer","description":"A 'cent' value representing the maximum cumulative amount that all successful payments can claim in the period.\n\nThis might be less than the `maximum_amount` requested due to proration on calendar aligned periods.\n"},"current_amount":{"type":"integer","description":"A 'cent' value representing the current cumulative amount that all successful payments have claimed in the period.\n"},"start_date":{"type":"string","format":"date","example":"2021-01-30","description":"The start date for the current period"},"end_date":{"type":"string","format":"date","example":"2021-02-06","description":"The end date for the current period, and start of the next period"}}},"GetConstraints":{"title":"Constraints State","type":"object","required":["maximum_individual_amount","periodic_limits"],"properties":{"valid_from":{"type":"string","format":"datetime","example":"2022-01-01T00:00:00.000Z","description":"Start date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ`\n"},"valid_to":{"type":"string","format":"datetime","example":"2022-12-31T23:59:59.999Z","description":"End date time for which the consent remains valid using format `YYYY-MM-DDTHH:mm:ss.sssZ`\n"},"maximum_individual_amount":{"type":"integer","description":"A 'cent' value representing the maximum amount that can be specified in a payment instruction"},"periodic_limits":{"type":"object","title":"Period States","description":"The state of the constraints utilisation within each periodic limit defined in the mandate creation.\nThere will always be at least 1 period state defined\n","properties":{"day":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current day"}]},"week":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current week period"}]},"fortnight":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current fortnight period"}]},"month":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current month period"}]},"half_year":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current half-year period"}]},"year":{"allOf":[{"$ref":"#/components/schemas/VRPPeriodState"},{"description":"Utilisation of this mandate within the current year period"}]}}}}},"ProviderReturnParametersPayment":{"type":"object","title":"Payment","description":"The Payment associated to the parameters submitted.","required":["type","payment_id"],"properties":{"type":{"description":"The resource type.","type":"string","enum":["payment"]},"payment_id":{"type":"string","description":"ID of the payment","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"}}},"ProviderReturnParametersMandate":{"type":"object","title":"Mandate","description":"The mandate associated to the parameters submitted.","required":["type","mandate_id"],"properties":{"type":{"description":"The resource type.","type":"string","enum":["mandate"]},"mandate_id":{"type":"string","description":"ID of the mandate","example":"0cd1b0f7-71bc-4d24-b209-95259dadcc20"}}},"ProviderReturnParametersResource":{"type":"object","description":"The resource associated to the parameters submitted.","oneOf":[{"$ref":"#/components/schemas/ProviderReturnParametersPayment"},{"$ref":"#/components/schemas/ProviderReturnParametersMandate"}],"discriminator":{"propertyName":"type","mapping":{"payment":"#/components/schemas/ProviderReturnParametersPayment","mandate":"#/components/schemas/ProviderReturnParametersMandate"}}},"ProviderReturnParametersResponse":{"title":"Resource","type":"object","required":["resource"],"properties":{"resource":{"$ref":"#/components/schemas/ProviderReturnParametersResource"}}},"WebhookCommon":{"type":"object","properties":{"type":{"type":"string"},"event_version":{"description":"The version of the event schema.\n","type":"integer"},"event_id":{"description":"Unique ID of the event.\n","type":"string","example":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941"}},"required":["type","event_version","event_id"]},"WebhookPaymentLinkPaymentCreated":{"title":"Payment Link Payment Created","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_link_payment_created"]},"event_version":{"enum":[1]},"payment_link_id":{"$ref":"#/components/schemas/PaymentLinkId"},"payment":{"type":"object","required":["id","created_at"],"properties":{"id":{"$ref":"#/components/schemas/PaymentId"},"created_at":{"type":"string","description":"Date and time the payment got created from the payment link","format":"datetime","example":"2021-12-25T15:00:00.000Z"}}}},"required":["payment_link_id","payment"]}]},"WebhookPaymentLinkDisabled":{"title":"Payment Link Disabled","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_link_disabled"]},"event_version":{"enum":[1]},"payment_link_id":{"$ref":"#/components/schemas/PaymentLinkId"},"disabled_reason":{"enum":["expired","cancelled","fulfilled"]},"disabled_at":{"type":"string","description":"Date and time the payment link was disabled","format":"datetime","example":"2021-12-25T15:00:00.000Z"}},"required":["payment_link_id","disabled_reason","disabled_at"]}]},"PaymentMethodBankTransferWebhook":{"title":"Bank Transfer","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The type of payment method.","enum":["bank_transfer"]},"provider_id":{"type":"string","description":"The provider Id the PSU will use for this payment. Can be `null` if the payment failed before successful provider selection.","example":["eg-provider"]},"scheme_id":{"type":"string","description":"The id of the scheme to make the payment over. Can be `null` if the payment failed before successful provider selection.","example":["payment_scheme"]}}},"PaymentMethodWebhook":{"title":"Payment Method","type":"object","oneOf":[{"$ref":"#/components/schemas/PaymentMethodBankTransferWebhook"},{"$ref":"#/components/schemas/PaymentMethodMandate"}],"discriminator":{"propertyName":"type","mapping":{"bank_transfer":"#/components/schemas/PaymentMethodBankTransferWebhook","mandate":"#/components/schemas/PaymentMethodMandate"}}},"WebhookPaymentAuthorized":{"title":"Authorized","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_authorized"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"payment_method":{"$ref":"#/components/schemas/PaymentMethodWebhook"},"authorized_at":{"type":"string","description":"Date and time the payment was authorized","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"payment_source":{"$ref":"#/components/schemas/PaymentSource"}},"required":["payment_id","payment_method","authorized_at"]}]},"WebhookPaymentExecuted":{"title":"Executed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_executed"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"payment_method":{"$ref":"#/components/schemas/PaymentMethodWebhook"},"executed_at":{"type":"string","description":"Date and time the payment executed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"payment_source":{"$ref":"#/components/schemas/PaymentSource"}},"required":["payment_id","payment_method","executed_at"]}]},"WebhookPaymentFailed":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_failed"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"payment_method":{"$ref":"#/components/schemas/PaymentMethodWebhook"},"failed_at":{"type":"string","description":"Date and time the payment failed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_stage":{"$ref":"#/components/schemas/PaymentFailureStage"},"failure_reason":{"$ref":"#/components/schemas/PaymentFailureReason"},"failure_funds_stage":{"$ref":"#/components/schemas/PaymentFailureFundsStage","description":"This is populated for Direct Debit payments only."},"payment_source":{"$ref":"#/components/schemas/PaymentSource"}},"required":["payment_id","payment_method","failed_at","failure_stage","failure_reason"]}]},"WebhookPaymentSettled":{"title":"Settled","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_settled"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"payment_method":{"$ref":"#/components/schemas/PaymentMethodWebhook"},"settled_at":{"type":"string","description":"Date and time the payment settled","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"payment_source":{"$ref":"#/components/schemas/SettledPaymentSource"},"user_id":{"$ref":"#/components/schemas/UserId"}},"required":["payment_id","payment_method","settled_at","payment_source","user_id"]}]},"WebhookPaymentCreditable":{"title":"Payment creditable","description":"Sent when the payment is ready to be credited to the user, and the services the user has paid for\nbe granted. Either the payment has settled, or any settlement risk has been accepted.\n\nThis webhook is optional, by default it is enabled and it will be sent on payment settlement. [Learn more about the configuration options](/docs/payment-risk-and-credit-notifications), and contact us if you would like this webhook to be disabled or to have a different behavior.\n","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_creditable"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"creditable_at":{"$ref":"#/components/schemas/CreditableAt"}},"required":["payment_id","creditable_at"]}]},"WebhookPaymentSettlementStalled":{"title":"Settlement Stalled","description":"Sent when the payment doesn't reach settled status after a certain amount of time.\n\nThis webhook is optional, and is disabled by default. Contact us if you would like this webhook to\nbe enabled.\n","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_settlement_stalled"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"settlement_stalled_at":{"$ref":"#/components/schemas/SettlementStalledAt"}},"required":["payment_id","settlement_stalled_at"]}]},"WebhookPaymentDisputed":{"title":"Payment disputed","description":"Sent when a indemnity claim has been made against a payment. This currently only applies to payments made via direct debit mandates.\n","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_disputed"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"disputed_at":{"$ref":"#/components/schemas/DisputedAt"},"disputed_reason":{"$ref":"#/components/schemas/DisputedReason"},"expires_at":{"type":"string","description":"The date and time that the dispute will expire and, by default, be resolved in favour of the end-user.","format":"datetime","example":"2025-09-02T00:00:00.000Z"}},"required":["payment_id","disputed_at","expires_at"]}]},"WebhookPaymentReversed":{"title":"Payment Reversed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_reversed"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"reversed_at":{"$ref":"#/components/schemas/ReversedAt"},"reversal_reason":{"$ref":"#/components/schemas/ReversalReason"}},"required":["payment_id","reversed_at","reversal_reason"]}]},"WebhookPaymentFundsReceived":{"title":"Payment Funds Received","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payment_funds_received"]},"event_version":{"enum":[1]},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"funds_received_at":{"type":"string","description":"The date and time that the Direct Debit payment arrived in the merchant account. The payment can still be reversed at this stage.","format":"datetime","example":"2021-12-25T15:00:00.000Z"}},"required":["payment_id","funds_received_at"]}]},"WebhookRefundExecuted":{"title":"Executed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["refund_executed"]},"event_version":{"enum":[1]},"refund_id":{"$ref":"#/components/schemas/PaymentRefundId"},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"executed_at":{"type":"string","description":"Date and time the refund executed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"scheme_id":{"$ref":"#/components/schemas/SchemeId"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["refund_id","payment_id","executed_at"]}],"example":{"type":"refund_executed","event_version":1,"event_id":"b8d4dda0-ff2c-4d77-a6da-4615e4bad941","refund_id":"43d12d0f-d775-410f-aaff-482200c17017","payment_id":"0afd1f6a-f611-48ce-9488-321129bb3a70","executed_at":"2021-12-25T15:00:00.000Z","scheme_id":"faster_payments_service","metadata":{"prop1":"value1","prop2":"value2"}}},"WebhookRefundFailed":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["refund_failed"]},"event_version":{"enum":[1]},"refund_id":{"$ref":"#/components/schemas/PaymentRefundId"},"payment_id":{"$ref":"#/components/schemas/PaymentId"},"failed_at":{"type":"string","description":"Date and time the refund failed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_reason":{"$ref":"#/components/schemas/OutboundPaymentFailureReason"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["refund_id","payment_id","failed_at","failure_reason"]}],"example":{"type":"refund_failed","event_version":1,"event_id":"c9e5eeb1-aa3d-5e88-b7eb-5726f5e5c052","refund_id":"54e23e1a-a886-521a-bbaa-593311cc4b81","payment_id":"1bae2a7b-a722-59dd-a599-432240dd4b81","failed_at":"2021-12-25T15:30:00.000Z","failure_reason":"insufficient_funds","metadata":{"prop1":"value1","prop2":"value2"}}},"WebhookPayoutBeneficiaryPaymentSource":{"title":"Payment source","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type \"payment_source\"","enum":["payment_source"]},"payment_source_id":{"type":"string"},"user_id":{"type":"string"}}},"WebhookPayoutBeneficiaryBusinessAccount":{"title":"Business account","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type \"business_account\"","enum":["business_account"]}}},"AccountHolderVerificationMatch":{"title":"Match","type":"object","properties":{"type":{"type":"string","enum":["match"],"description":"Type `match` - Name and IBAN match the bank records."}},"required":["type"]},"AccountHolderVerificationPartialMatch":{"title":"Partial Match","type":"object","description":"The provided name partially matches the account holder name on record with the bank.","properties":{"type":{"type":"string","enum":["partial_match"],"description":"Type `partial_match` - Name is similar, but not an exact match."},"account_holder_name":{"type":"string","description":"The actual account holder name returned by the bank."}},"required":["type","account_holder_name"]},"AccountHolderVerificationNoMatch":{"title":"No Match","type":"object","properties":{"type":{"type":"string","enum":["no_match"],"description":"Type `no_match` - The name and IBAN do not match the bank’s records."}},"required":["type"]},"AccountHolderVerificationMatchNotPossible":{"title":"Match Not Possible","type":"object","properties":{"type":{"type":"string","enum":["match_not_possible"],"description":"Type `match_not_possible` - The VoP scheme was unable to perform a match."},"reason":{"type":"string","description":"The reason why account holder name verification could not be performed.\n\nThe reason can be one of the following:\n\n- `Bank unable to match`: Account closed, couldn't be found or similar.\n- `party agent not part of scheme`: Bank not part of the VoP scheme.\n"}},"required":["type","reason"]},"AccountHolderVerificationMatchResult":{"oneOf":[{"$ref":"#/components/schemas/AccountHolderVerificationMatch"},{"$ref":"#/components/schemas/AccountHolderVerificationPartialMatch"},{"$ref":"#/components/schemas/AccountHolderVerificationNoMatch"},{"$ref":"#/components/schemas/AccountHolderVerificationMatchNotPossible"}],"discriminator":{"propertyName":"type","mapping":{"match":"#/components/schemas/AccountHolderVerificationMatch","partial_match":"#/components/schemas/AccountHolderVerificationPartialMatch","no_match":"#/components/schemas/AccountHolderVerificationNoMatch","match_not_possible":"#/components/schemas/AccountHolderVerificationMatchNotPossible"}}},"AccountHolderVerificationCompleted":{"title":"Completed","type":"object","properties":{"status":{"type":"string","enum":["completed"],"description":"A match result was returned."},"match_result":{"$ref":"#/components/schemas/AccountHolderVerificationMatchResult"}},"required":["status","match_result"]},"AccountHolderVerificationFailed":{"title":"Failed","type":"object","properties":{"status":{"type":"string","enum":["failed"],"description":"A match result was not returned."},"failure_reason":{"type":"string","description":"The reason why the verification failed.\nThe failure reason can be one of the following:\n- `VoP scheme provider error`: Failure with one of the providers in the scheme - likely to be transitory.\n- `Internal error`: An internal error occurred while processing the request.\n"}},"required":["status","failure_reason"]},"AccountHolderVerification":{"oneOf":[{"$ref":"#/components/schemas/AccountHolderVerificationCompleted"},{"$ref":"#/components/schemas/AccountHolderVerificationFailed"}],"discriminator":{"propertyName":"status","mapping":{"completed":"#/components/schemas/AccountHolderVerificationCompleted","failed":"#/components/schemas/AccountHolderVerificationFailed"}}},"WebhookPayoutBeneficiaryExternalAccount":{"title":"External account","type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Type \"external_account\"","enum":["external_account"]},"account_holder_verification":{"$ref":"#/components/schemas/AccountHolderVerification"}}},"WebhookPayoutExecutedBeneficiaryUserDetermined":{"title":"User determined","type":"object","required":["type","user","provider_id","account_holder_name","account_identifiers"],"properties":{"type":{"type":"string","description":"Type \"user_determined\"","enum":["user_determined"]},"user":{"$ref":"#/components/schemas/PaymentUser"},"provider_id":{"description":"The id of the banking provider associated to the account identifiers present in this object.\n","type":"string"},"account_holder_name":{"description":"The name of the account holder.\n","type":"string"},"account_identifiers":{"type":"array","description":"Account routing information associated to the beneficiary of the payout.\n","items":{"$ref":"#/components/schemas/AccountIdentifier"}}}},"WebhookPayoutExecutedBeneficiary":{"type":"object","oneOf":[{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryPaymentSource"},{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryBusinessAccount"},{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryExternalAccount"},{"$ref":"#/components/schemas/WebhookPayoutExecutedBeneficiaryUserDetermined"}],"discriminator":{"propertyName":"type","mapping":{"payment_source":"#/components/schemas/WebhookPayoutBeneficiaryPaymentSource","business_account":"#/components/schemas/WebhookPayoutBeneficiaryBusinessAccount","external_account":"#/components/schemas/WebhookPayoutBeneficiaryExternalAccount","user_determined":"#/components/schemas/WebhookPayoutExecutedBeneficiaryUserDetermined"}}},"WebhookPayoutExecuted":{"title":"Executed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payout_executed"]},"event_version":{"enum":[1]},"payout_id":{"$ref":"#/components/schemas/PayoutId"},"executed_at":{"type":"string","description":"Date and time the payout was executed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"beneficiary":{"$ref":"#/components/schemas/WebhookPayoutExecutedBeneficiary"},"scheme_id":{"$ref":"#/components/schemas/SchemeId"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["payout_id","executed_at","beneficiary","scheme_id"]}]},"WebhookPayoutFailedBeneficiaryUserDetermined":{"title":"User determined","type":"object","required":["type","user"],"properties":{"type":{"type":"string","description":"Type \"user_determined\"","enum":["user_determined"]},"user":{"$ref":"#/components/schemas/PaymentUser"},"provider_id":{"description":"The id of the banking provider associated to the account identifiers present in this object.\n\nNot available if the payout failed during authorization or verification.\n","type":"string"},"account_holder_name":{"description":"The name of the account holder.\n\nNot available if the payout failed during authorization or verification.\n","type":"string"},"account_identifiers":{"type":"array","description":"Account routing information associated to the beneficiary of the payout.\n\nNot available if the payout failed during authorization or verification.\n","items":{"$ref":"#/components/schemas/AccountIdentifier"}}}},"WebhookPayoutFailedBeneficiary":{"type":"object","oneOf":[{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryPaymentSource"},{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryBusinessAccount"},{"$ref":"#/components/schemas/WebhookPayoutBeneficiaryExternalAccount"},{"$ref":"#/components/schemas/WebhookPayoutFailedBeneficiaryUserDetermined"}],"discriminator":{"propertyName":"type","mapping":{"payment_source":"#/components/schemas/WebhookPayoutBeneficiaryPaymentSource","business_account":"#/components/schemas/WebhookPayoutBeneficiaryBusinessAccount","external_account":"#/components/schemas/WebhookPayoutBeneficiaryExternalAccount","user_determined":"#/components/schemas/WebhookPayoutFailedBeneficiaryUserDetermined"}}},"WebhookPayoutFailed":{"title":"Failed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["payout_failed"]},"event_version":{"enum":[1]},"payout_id":{"$ref":"#/components/schemas/PayoutId"},"failed_at":{"type":"string","description":"Date and time the payout failed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_reason":{"$ref":"#/components/schemas/OutboundPaymentFailureReason"},"beneficiary":{"$ref":"#/components/schemas/WebhookPayoutFailedBeneficiary"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["payout_id","failed_at","failure_reason","beneficiary"]}]},"WebhookMandateAuthorized":{"title":"Mandate Authorized","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["mandate_authorized"]},"event_version":{"enum":[1]},"mandate_id":{"$ref":"#/components/schemas/MandateId"},"authorized_at":{"type":"string","description":"Date and time the mandate became authorized","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"statement_reference":{"type":"string","description":"Statement reference for the mandate"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["mandate_id","authorized_at","statement_reference"]}]},"WebhookMandateFailed":{"title":"Mandate Failed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["mandate_failed"]},"event_version":{"enum":[1]},"mandate_id":{"$ref":"#/components/schemas/MandateId"},"failed_at":{"type":"string","description":"Date and time the mandate failed","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"failure_stage":{"$ref":"#/components/schemas/MandateFailureStage"},"failure_reason":{"$ref":"#/components/schemas/MandateFailureReason"},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["mandate_id","failure_reason","failure_stage","failed_at"]}]},"WebhookMandateRevoked":{"title":"Mandate Revoked","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["mandate_revoked"]},"event_version":{"enum":[1]},"mandate_id":{"$ref":"#/components/schemas/MandateId"},"revoked_at":{"type":"string","description":"Date and time the mandate became revoked","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"revocation_source":{"$ref":"#/components/schemas/RevocationSource"},"revocation_reason":{"type":"string","description":"The reason why the mandate was revoked. This is currently only available for direct debit mandates."},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["mandate_id","revoked_at","revocation_source"]}]},"WebhookMandateRemitterChanged":{"title":"Mandate Remitter Changed","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["mandate_remitter_changed"]},"event_version":{"enum":[1]},"mandate_id":{"$ref":"#/components/schemas/MandateId"},"remitter_changed_at":{"type":"string","description":"Date and time the remitter details of the mandate were changed.","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"account_holder_name":{"type":"string","description":"The name associated to the new remitter account."},"account_identifier":{"$ref":"#/components/schemas/PaymentAccountIdentifier","description":"The account id of the new remitter account."},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["mandate_id","remitter_changed_at","account_holder_name","account_identifier"]}]},"MandateInitialPayment":{"title":"Initial Payment","type":"object","required":["id","created_at"],"properties":{"id":{"type":"string","description":"Unique ID of the payment","example":"be6db706-68f1-4e9c-ab09-b83d8e3ea60d"},"created_at":{"type":"string","description":"Date and time the payment was created","format":"datetime","example":"2021-12-25T15:00:00.000Z"}}},"WebhookMandateInitialPaymentCreated":{"title":"Mandate Initial Payment Created","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["mandate_initial_payment_created"]},"event_version":{"enum":[1]},"mandate_id":{"$ref":"#/components/schemas/MandateId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"payment":{"$ref":"#/components/schemas/MandateInitialPayment"}},"required":["mandate_id","payment"]}]},"WebhookExternalPaymentReceived":{"title":"External Payment","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["external_payment_received"]},"event_version":{"enum":[1]},"transaction_id":{"$ref":"#/components/schemas/TransactionId"},"currency":{"$ref":"#/components/schemas/MerchantAccountCurrencyCode"},"amount_in_minor":{"type":"integer","minimum":1},"settled_at":{"type":"string","description":"Date and time the transaction settled","format":"datetime","example":"2021-12-25T15:00:00.000Z"},"merchant_account_id":{"$ref":"#/components/schemas/MerchantAccountId"},"remitter":{"type":"object","properties":{"account_holder_name":{"description":"The name of the external account holder.\n","type":"string"},"account_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/AccountIdentifier"}},"reference":{"type":"string","description":"The reference for the external payment."}},"required":["account_holder_name","account_identifiers"]}},"required":["transaction_id","settled_at","currency","amount_in_minor","remitter","merchant_account_id"]}]},"WebhookBalanceNotification":{"title":"Balance Notification","allOf":[{"$ref":"#/components/schemas/WebhookCommon"},{"type":"object","properties":{"type":{"enum":["balance_notification"]},"event_version":{"enum":[1]},"merchant_account_id":{"$ref":"#/components/schemas/MerchantAccountId"},"current_balance_in_minor":{"$ref":"#/components/schemas/CurrentBalance"},"available_balance_in_minor":{"$ref":"#/components/schemas/AvailableBalance"},"threshold_in_minor":{"description":"The balance threshold, expressed in the smallest denomination of the account's currency.\n","type":"integer"},"status":{"type":"string","description":"Whether the balance is approaching the threshold, below the threshold, or has recovered.","enum":["approaching_threshold","below_threshold","recovered"]}},"required":["merchant_account_id","current_balance_in_minor","available_balance_in_minor","status"]}]}},"headers":{"Tl-Trace-Id":{"schema":{"type":"string"},"description":"Unique ID per request.\nWe recommend logging this to share with us when investgating any issues.\n"},"Tl-Should-Retry":{"schema":{"type":"boolean"},"description":"Whether retrying with the same idempotency key could return a different result. If you receive a value of true, you should retry your request to get the true result of the operation."}}},"x-readme":{"explorer-enabled":false}}