TrueLayer

https://docs.truelayer.com/
Admin
TrueLayer is an open banking platform that provides APIs for developers to securely integrate...
Tokens:845,900
Snippets:5,163
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start authorisation flow response example

Source: https://docs.truelayer.com/docs/authorisation-flow-actions

Example JSON response indicating that the next required action is provider_selection.

```json
{
  "authorization_flow": {
    "actions": {
      "next": {
        "type": "provider_selection",
        "providers": [
          {
            "id": "ob-bank-name",
            "display_name": "Bank Name",
            "icon_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg",
            "logo_uri": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg",
            "bg_color": "#000000",
            "country_code": "AT",
            "search_aliases": [
              "string"
            ]
          }
        ]
      }
    }
  },
  "status": "authorizing"
}
```

--------------------------------

### Initialize and start the Web SDK

Source: https://docs.truelayer.com/docs/web-sdk

Examples showing how to mount the SDK container and start the payment flow, either combined or as separate steps.

```javascript
initWebSdk({
    hostedResultScreen: {
       returnUri: merchant_return_uri,
    },
  //...
})
  .mount(node)
  .start({
    paymentId: payment.id,
    resourceToken: payment.resource_token
  })
```

```javascript
const { mount, start, cleanup } = initWebSdk({
    hostedResultScreen: {
            returnUri: merchant_return_uri,
          },
  })

  // later, when the target for the button is ready 
  mount(node)
  
  // later, when the payment is available
  start({
      paymentId: payment.id,
      resourceToken: payment.resource_token,
  })
```

--------------------------------

### Start Payout Authorization Flow Example

Source: https://docs.truelayer.com/reference/webhook-mandates

Example request body for initiating a payout authorization flow, requiring a registered return URI.

```json
{
  "redirect": {
    "return_uri": "https://my-site.com/payout-return"
  }
}
```

--------------------------------

### Account ID Example

Source: https://docs.truelayer.com/reference/getaccountbalance

Example value for the account_id path parameter.

```json
"f1234560abf9f57287637624def390871"
```

--------------------------------

### Product Item Schema Example

Source: https://docs.truelayer.com/reference/webhook-payouts

Example of the product item object structure.

```json
{
  "name": "Oak Table",
  "price_in_minor": 1,
  "quantity": 1,
  "url": "https://tablesrus.com/oak-table-42"
}
```

--------------------------------

### Get Payment Refund Example

Source: https://docs.truelayer.com/openapi/payments-api-v3.json

Example of a unique ID for a refund used in the path parameter.

```json
"example":"43d12d0f-d775-410f-aaff-482200c17017"
```

--------------------------------

### Initialize Web SDK

Source: https://docs.truelayer.com/docs/epp-to-web-sdk-migration-guide

Initialize the SDK and mount the Pay button to the DOM.

```javascript
const { start, mount } = initWebSdk({
  hostedResultScreen: {
    returnUri: 'https://example.org/return-page'
  },
  ...
})

// mount the Pay button (stays in a loading state until `start(...)` is called)
mount(document.getElementById('your-container-id'))

// pass the `paymentId` and `resourceToken` to enable the Pay button
start({ paymentId, resourceToken })
```

--------------------------------

### Get Payout Response Example

Source: https://docs.truelayer.com/openapi/payments-api-v3.json

Example JSON response for retrieving payout details for an external account.

```json
{"id":"0cd1b0f7-71bc-4d24-b209-95259dadcc20","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
```

--------------------------------

### Get Payout Response with Verification Details

Source: https://docs.truelayer.com/docs/payouts-account-holder-verification

Example of a successful Get Payout response containing the account_holder_verification object.

```json
{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "merchant_account_id": "ae094a73-d874-4241-a65f-6dcda7ac07b1",
  "amount_in_minor": 100,
  "currency": "EUR",
  "beneficiary": {
    "type": "external_account",
    "reference": "a-reference",
    "account_holder_name": "John Doe",
    "account_identifiers": [
      {
        "type": "iban",
        "iban": "FR1234567890123"
      }
    ],
    "account_holder_verification": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "match_result": {
        "type": "match"
      }
    }
  },
  "scheme_id": "faster_payments_service",
  "created_at": "2021-12-25T14:00:00.000Z",
  "status": "executed",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  }
}
```

--------------------------------

### Get Connected Accounts Response Example

Source: https://docs.truelayer.com/reference/get-accounts

Example response containing a list of connected accounts and pagination details.

```json
{
  "items": [
    {
      "id": "56c7b029e0f8ec5a2334fb0ffc2fface",
      "type": "account",
      "account_type": "current",
      "customer_segment": "retail",
      "currency": "GBP",
      "account_identifiers": [
        {
          "type": "sort_code_account_number",
          "sort_code": "560029",
          "account_number": "26207729"
        },
        {
          "type": "iban",
          "iban": "GB32CLRB04066800012315"
        }
      ],
      "bic": "MONZGB2LXXX",
      "account_holder_names": [
        "John Smith"
      ]
    }
  ],
  "pagination": {
    "next_cursor": "bWFuZGF0ZXM6MmUwNDk0MTMK"
  }
}
```

--------------------------------

### Example Configuration Object

Source: https://docs.truelayer.com/reference/create-payment

A sample JSON structure demonstrating various payment configuration fields including provider selection, redirect URIs, and user account selection.

```json
{
  "provider_selection": {},
  "scheme_selection": {},
  "redirect": {
    "return_uri": "https://my-site.com/payment-return"
  },
  "form": {
    "input_types": [
      "text"
    ]
  },
  "consent": {},
  "user_account_selection": {}
}
```

--------------------------------

### TrueLayerUI.init (Standard Activity)

Source: https://docs.truelayer.com/docs/android-sdk

Initialize the TrueLayer SDK and launch the processor using standard Activity intents.

```APIDOC
## TrueLayerUI.init

### Description
Initializes the SDK configuration and launches the processor via an Intent. Results are handled in onActivityResult.

### Usage
```kotlin
TrueLayerUI.init(context = applicationContext) {
    environment = Environment.PRODUCTION
    httpConnection = HttpConnectionConfiguration(timeoutMs = 35000)
}

val intent = ProcessorActivityContract().createIntent(this, mandateContext)
startActivityForResult(intent, 0)
```
```

--------------------------------

### TrueLayer.Payments.manager.configure(environment:)

Source: https://docs.truelayer.com/docs/authorise-mandates-with-the-ios-sdk

Initializes the SDK with the specified environment. This should be called once during application startup.

```APIDOC
## TrueLayer.Payments.manager.configure(environment:)

### Description
Initializes the TrueLayer Payments SDK. This method must be called once before processing any mandates.

### Parameters
- **environment** (Enum) - Required - The environment to use: `.production` or `.sandbox`.
```

--------------------------------

### Get payout status response

Source: https://docs.truelayer.com/docs/make-a-payout-to-an-account-that-paid-in

Example response from the GET /v3/payouts/{id} endpoint, providing detailed status and beneficiary information.

```json
{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
  "amount_in_minor": 0,
  "currency": "GBP",
  "beneficiary": {
    "type": "external_account",
    "reference": "string",
    "account_holder_name": "string",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": 560029,
        "account_number": 26207729
      },
      {
        "type": "iban",
        "iban": "GB32CLRB04066800012315"
      }
    ]
  },
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "scheme_id": "faster_payments_service",
  "status": "pending",
  "created_at": "string"
}
```

--------------------------------

### Finland Signup+ Payment creation example

Source: https://docs.truelayer.com/docs/integrate-signup-in-finland

A complete example of a payment creation request configured for a Finnish Signup+ integration.

```json
{
	"amount_in_minor": 10,
	"currency": "EUR",
	"payment_method": {
		"beneficiary": {
			"merchant_account_id": "<Merchant_Account_ID",
			"reference": "Test payment",
			"type": "merchant_account"
		},
		"filter": {
			"countries": [
				"FI"
			],
			"customer_segments": [
				"retail"
			],
			"excludes": {
				"provider_ids": [
					"<provider_id>"
				]
			},
			"release_channel": "general_availability"
		},
		"provider_selection": {
			"type": "user_selected"
		},
		"type": "bank_transfer"
	},
	"related_products": {
		"signup_plus": {}
	},
	"user": {
		"address": {
			...
		},
		"date_of_birth": "1992-11-28",
		"email": "john@sandbridge.com",
		"name": "Jonathan Sandbridge",
		"phone": "+44123456789"
	}
  }
```

--------------------------------

### Get Providers 200 Response Example

Source: https://docs.truelayer.com/reference/getproviders

Example JSON response body for a successful request to retrieve a list of available providers.

```json
[
  {
    "provider_id": "mock",
    "display_name": "Mock",
    "country": "uk",
    "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/mock.svg",
    "scopes": [
      "accounts",
      "balance",
      "cards",
      "info",
      "transactions",
      "offline_access"
    ],
    "availability": {
      "recommended_status": "healthy",
      "updated_at": "2023-05-23T10:11:54.501Z"
    }
  },
  {
    "provider_id": "ob-transferwise",
    "display_name": "Wise",
    "country": "uk",
    "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/transferwise.svg",
    "scopes": [
      "accounts",
      "balance",
      "transactions",
      "offline_access"
    ],
    "availability": {
      "recommended_status": "healthy",
      "updated_at": "2023-05-23T10:11:54.501Z"
    }
  },
  {
    "provider_id": "ob-lloyds-business",
    "display_name": "Lloyds Business",
    "country": "uk",
    "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/lloyds.svg"
```

--------------------------------

### Hosted page URL examples

Source: https://docs.truelayer.com/docs/hosted-page

These URLs demonstrate the required parameters for initiating a hosted page session in both sandbox and production environments.

```text
https://app.truelayer-sandbox.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3
```

```text
https://app.truelayer.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3
```

```text
https://payment.truelayer-sandbox.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3
```

```text
https://payment.truelayer.com/payments?payment_id=8c905ec4-d51c-4ca8-8541-0538403ead0d&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InBheW1lbnQiLCJjbGllbnRfaWQiOiJzYW5kYm94LXRvbXRlc3QtYTRkNDMyIiwianRpIjoiOGM5MDVlYzQtZDUxYy00Y2E4LTg1NDEtMDUzODQwM2VhZDBkIiwibmJmIjoxNzIwMDk4NzgyLCJleHAiOjE3MjAwOTk2ODIsImlzcyI6Imh0dHBzOi8vYXBpLnRydWVsYXllci1zYW5kYm94LmNvbS9wYXltZW50cy1nYXRld2F5IiwiYXVkIjoiaHR0cHM6Ly9hcGkudHJ1ZWxheWVyLXNhbmRib3guY29tIn0.ZAEz21ZrTgGNZwVwfhquxCN2aO6qyizSb2sri89s3ywkF7c0lw2fhwfgTpv1aPmVbd8YwBur7vgvMa2xQFhAgzTMqfWEZ_Xy6-zjxYGlkNVkysrF1gOPYlGvPnizOZipPU_qekPnQUpe7VT2MldCggpOKip6iIwM5SBK4vfHZxOkg36fa1-gQLmfLxamCjeqz7PiK7e_yQAR6BmxZuuNsCEVCaY0ivIjborBYVGWM5fDcYO3paqvdjmqSLuEENiHnA0sMaoahXrPK-fSSXESxHhtc-_3P3Y1_Dm1ogj-xoLhuky0SLYWThnd2757aqoFR_v2XbTwt86QzY5OnZNdUg&return_uri=https://example.com/redirect/v3
```

--------------------------------

### Install Cargo and TrueLayer CLI

Source: https://docs.truelayer.com/docs/develop-and-test-a-webhook-endpoint-locally

Install the Rust toolchain and the TrueLayer CLI from source.

```bash
curl https://sh.rustup.rs -sSf | sh
```

```bash
cargo install --git https://github.com/TrueLayer/truelayer-cli.git
```

--------------------------------

### Initialise the TrueLayer SDK

Source: https://docs.truelayer.com/docs/authorise-mandates-with-the-android-sdk

Import the necessary configuration classes and the TrueLayerUI entry point to initialise the SDK.

```kotlin
import com.truelayer.payments.core.domain.configuration.Environment
import com.truelayer.payments.core.domain.configuration.HttpConnectionConfiguration
import com.truelayer.payments.core.domain.configuration.HttpLoggingLevel
import com.truelayer.payments.ui.TrueLayerUI
```

--------------------------------

### Get Card Response Payload

Source: https://docs.truelayer.com/openapi/data-api-v1.json

Example JSON response for a card retrieval request.

```json
{"results":[{"account_id":"f7b093437032c216d4350b7d442b9c5ccc0e9f19","card_network":"VISA","card_type":"CREDIT","currency":"GBP","display_name":"Club Credit Card","partial_card_number":"0044","name_on_card":"A. N. Other","valid_from":"2017-01","valid_to":"2018-01","update_timestamp":"2017-02-07T17:29:24.740802Z","provider":{"provider_id":"lloyds"}}]}
```

--------------------------------

### GET payment response example

Source: https://docs.truelayer.com/docs/create-a-payment.md

The JSON structure returned when successfully querying a payment by its ID.

```json
{
  "id": "0afd1f6a-f611-48ce-9488-321129bb3a70",
  "amount_in_minor": 0,
  "currency": "GBP",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": [
          "GB"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ],
        "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      },
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme"
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "string",
      "account_holder_name": "string",
      "verification": {
        "type": "automated",
        "remitter_name": true,
        "remitter_date_of_birth": true
      }
    }
  },
  "created_at": "string",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "status": "authorization_required"
}
```

--------------------------------

### Provider Metadata Examples

Source: https://docs.truelayer.com/reference/submit-consent-mandate

Examples for provider display name, URIs, and background color.

```json
"example": "Bank Name"
```

```json
"example": "https://truelayer-provider-assets.s3.amazonaws.com/global/icon/generic.svg"
```

```json
"example": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/generic.svg"
```

```json
"example": "#000000"
```

--------------------------------

### Get Card Transactions Response Payload

Source: https://docs.truelayer.com/openapi/data-api-v1.json

Example JSON response containing a list of card transactions.

```json
{"results":[{"transaction_id":"a15d8156569ba848d84c07c34d291bca","normalised_provider_transaction_id":"txn-ajdifh38fheu5hgue","provider_transaction_id":"9882ks-00js","timestamp":"2018-01-16T00:00:00+00:00","description":"SAINSBURYS SMRKT STORE 128","amount":24.25,"currency":"GBP","transaction_type":"DEBIT","transaction_category":"PURCHASE","transaction_classification":["Shopping","Groceries"],"merchant_name":"Sainsburys","running_balance":{"amount":1238.6,"currency":"GBP"},"meta":{"cardNumber":"1234********5678","location":"INTERNET"}},{"transaction_id":"af4d5470cc7ad6a83a02335ab8053481","normalised_provider_transaction_id":"txn-2jdh8whf8w9rh3udh","provider_transaction_id":"33b5555724","timestamp":"2018-03-19T00:00:00","description":"TALKTALK TELECOM","amount":46.82,"currency":"GBP","transaction_type":"DEBIT","transaction_category":"PURCHASE","transaction_classification":["Bills and Utilities","Internet"],"merchant_name":"Talktalk","running_balance":{"amount":1262.85,"currency":"GBP"},"meta":{"provider_transaction_category":"DEB","cardNumber":"1234********5678","location":"INTERNET"}}]}
```

--------------------------------

### Initialize Web SDK integration

Source: https://docs.truelayer.com/docs/web-sdk

Configures the SDK with event callbacks, UI settings, and environment flags. Use the returned functions to manage the SDK lifecycle and payment initiation.

```javascript
import { initWebSdk } from '@truelayer-web-sdk'

const {
  // Function to mount the container where the Pay button will be
  mount,
  // Function to initiate the Pay button with a payment
  start,
  // Function to remove event listeners used by the SDK, when the SDK is not longer needed.
  cleanup,
  // Function to dynamically open the learn more modal
  openLearnMoreModal,
} = initWebSdk({
  onDone: info => {
    console.log(`Payment status: ${info.resultStatus}`)
  },
  onCancel: () => {
    console.log('Payment cancelled')
  },
  onError: error => {
    console.error('Payment error:', error)
  },
  onPayButtonClicked: () => {
    console.log('Pay button clicked')
  },
  onNavigation: page => {
    console.log('Page:', page)
  },
   onExpired: () => {
    console.log('The payment has expired')
  },
  uiSettings: {
    recommendedPaymentMethod: true,
    size: 'large',
    borderRadius: 8,
  },
  production: false,
})
```

--------------------------------

### Get Card Balance Response Payload

Source: https://docs.truelayer.com/openapi/data-api-v1.json

Example JSON response for a card balance retrieval request.

```json
{"results":[{"available":3279,"currency":"GBP","current":20,"credit_limit":3300,"last_statement_balance":420,"last_statement_date":"2017-01-28","payment_due":5,"payment_due_date":"2017-02-24","update_timestamp":"2017-02-247T17:29:24.740802Z"}]}
```

--------------------------------

### Initialize Web SDK v1

Source: https://docs.truelayer.com/docs/web-sdk-v0-to-v1-migration-guide

Initializes the SDK with mandatory configuration and the onStartFlow callback to handle payment creation upon user interaction.

```json
const { start, mount } = initWebSdk({
  currency: 'GBP' | 'EUR',
  clientId: 'your-client-id',
  returnUri: 'https://example.org/return-page',
  user: {
    email: 'john.doe@example.org',
  },
  async onStartFlow() {
    // `createPayment` is an example of your function (not part of the TrueLayer Web SDK)
    // that makes a server call to create the payment
    const { paymentId, resourceToken } = await createPayment()

    // pass the `paymentId` and `resourceToken` to kick off the payment flow
    start({ paymentId, resourceToken })
  },
  ...
})

// mount the Pay button
mount(document.getElementById('your-container-id'))
```

--------------------------------

### GET /refunds response structure

Source: https://docs.truelayer.com/docs/payout-and-refund-returns

Example of a refund response showing a failed status due to a return.

```json
[
   {
      "id":"5000fc14-a6ec-47d2-9ed0-4a1511d3c113",
      "amount_in_minor":10,
      "currency":"GBP",
      "status":"failed",
      "reference":"TUOYAP",
      "created_at":"2024-03-08T12:03:19.066995832Z",
      "authorized_at":"2024-03-08T12:03:19.511051580Z",
      "executed_at":"2024-03-08T12:03:20.457Z",
      "failed_at":"2024-03-08T12:03:22.447Z",
      "failure_reason":"returned"
   }
]
```

--------------------------------

### OpenAPI Payout Authorization Flow Definitions

Source: https://docs.truelayer.com/reference/webhook-payouts

Contains the OpenAPI path definitions for getting and starting a payout authorization flow.

```json
"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": {
```

--------------------------------

### Install and remove SDK packages

Source: https://docs.truelayer.com/docs/epp-to-web-sdk-migration-guide

Commands to switch from the legacy embedded payment page package to the new Web SDK.

```bash
npm i truelayer-web-sdk

npm uninstall truelayer-embedded-payment-page
```

```bash
yarn add truelayer-web-sdk

yarn remove truelayer-embedded-payment-page
```

```bash
pnpm install truelayer-web-sdk

pnpm uninstall truelayer-embedded-payment-page
```

--------------------------------

### TrueLayerUI.init

Source: https://docs.truelayer.com/docs/android-sdk

Initializes the TrueLayer SDK with the application context and optional configuration for environment and HTTP settings.

```APIDOC
## TrueLayerUI.init

### Description
Initializes the SDK with your application context. This must be called before invoking any other SDK method.

### Parameters
- **context** (Context) - Required - The application context.
- **environment** (Environment) - Optional - The environment to use (PRODUCTION or SANDBOX).
- **httpConnection** (HttpConnectionConfiguration) - Optional - Custom HTTP configuration including timeout and logging level.
```

--------------------------------

### Get User Data Success Response

Source: https://docs.truelayer.com/openapi/signup.json

Example of a successful 200 OK response containing user data retrieved from a mandate.

```json
{"title":"Mr","first_name":"Sherlock","last_name":"Holmes","date_of_birth":"1854-01-06","address":{"address_line1":"221B Baker St","address_line2":"Flat 2","city":"London","state":"Greater London","zip":"NW1 6XE","country":"GB"},"account_details":{"account_number":"41921234","sort_code":"04-01-02","iban":"GB71MONZ04435141923452","provider_id":"ob-monzo"}}
```

--------------------------------

### GET /transactions response structure

Source: https://docs.truelayer.com/docs/payout-and-refund-returns

Example of an external payment object containing the return_for field, which links to the original payout ID.

```json
{
			"type": "external_payment",
			"id": "f1a36337-4c22-42e7-bc30-0599a32aa6e9",
			"currency": "GBP",
			"amount_in_minor": 1,
			"status": "settled",
			"settled_at": "2024-03-15T17:22:05.450Z",
			"remitter": {
				"account_holder_name": "xxx",
				"account_identifier": {
					"type": "sort_code_account_number",
					"sort_code": "040075",
					"account_number": "58114637"
				},
				"account_identifiers": [
					{
						"type": "sort_code_account_number",
						"sort_code": "010101",
						"account_number": "12345678"
					},
					{
						"type": "iban",
						"iban": "GB24BARC20038498146991"
					}
				],
				"reference": "xxx"
			},
			"return_for": {
				"type": "identified",
				"returned_id": "9e07d528-b285-4875-b26a-ef6644d804aa"
			}
		},
		{
			"type": "payout",
			"id": "{placeholder-id}",
			"currency": "GBP",
			"amount_in_minor": 1,
			"status": "executed",
			"created_at": "2024-03-15T17:04:02.561706613Z",
			"executed_at": "2024-03-15T17:04:05.763Z",
			"beneficiary": {
				"type": "external_account",
				"account_holder_name": "xxx",
				"account_identifier": {
					"type": "sort_code_account_number",
					"sort_code": "010101",
					"account_number": "12345678"
				},
				"account_identifiers": [
					{
						"type": "sort_code_account_number",
						"sort_code": "010101",
						"account_number": "12345678"
					},
					{
						"type": "iban",
						"iban": "GB24BARC20038498146991"
					}
				],
				"reference": "xxx"
			},
			"context_code": "withdrawal",
			"payout_id": "9e07d528-b285-4875-b26a-ef6644d804aa",
			"returned_by": "f1a36337-4c22-42e7-bc30-0599a32aa6e9"
		}
```

--------------------------------

### Hosted Page Parameters Example

Source: https://docs.truelayer.com/reference/create-payment

Configuration parameters for initializing a hosted payment page, including redirect URIs and localization settings.

```json
{
  "return_uri": "https://my-domain.com/my-return-page",
  "country_code": "GB",
  "language_code": "en",
  "max_wait_for_result": 3
}
```

--------------------------------

### Install SDK via npm

Source: https://docs.truelayer.com/docs/react-native-sdk

Use this command to add the SDK dependency to your project using npm.

```bash
npm install rn-truelayer-payments-sdk --save
```

--------------------------------

### Account Holder Verification Response Examples

Source: https://docs.truelayer.com/docs/account-holder-verification-1

These JSON payloads represent the various states and results returned by the GET /v3/account-holder-verifications/requests/{id} endpoint.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "status": "pending"
}
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "match_result": {
    "type": "match"
  }
}
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "no_match"
  }
}
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "completed",
  "match_result": {
    "type": "partial_match",
    "account_holder_name": "Jean D."
  }
}
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "completed",
  "match_result": {
    "type": "match_not_possible",
    "failure_reason": "Bank unable to match"
  }
}
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "status": "failed",
  "failure_reason": "provider_error"
}
```

--------------------------------

### Install TrueLayer Web SDK via package manager

Source: https://docs.truelayer.com/docs/web-sdk

Commands to install the SDK using common JavaScript package managers.

```bash
npm i truelayer-web-sdk
```

```bash
yarn add truelayer-web-sdk
```

```bash
pnpm install truelayer-web-sdk
```

--------------------------------

### Retrieve Signup+ VRP mandate data

Source: https://docs.truelayer.com/docs/variable-recurring-payments-integration

Example of the GET request URL structure for fetching user data associated with a specific mandate ID.

```http
https://api.truelayer-sandbox.com/signup-plus/mandates?mandate_id={example_mandate_id}
```

--------------------------------

### Get transactions request using cURL

Source: https://docs.truelayer.com/docs/get-your-merchant-account-transactions-or-payment-sources

Example request to retrieve transactions for a specific merchant account within a defined ISO-8601 date range.

```curl
curl --request GET \
  --url 'https://api.truelayer-sandbox.com/v3/merchant-accounts/200552da-13da-43c5-a9ba-04ee1502ac57/transactions?from=2024-04-01T13%3A13%3A40Z&to=2024-04-17T13%3A42%3A32.846Z' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Idempotency-Key: {random_UUID}' \
  --header 'Tl-Signature: {signature}'
```
Tokens:
Raw