Deposits

Learn how to set up, execute, and monitor progress of a deposit.

📘

This feature is in private beta and is currently available to a limited number of clients. To join our private beta, contact Client Care.

A deposit is a one-time payment into your wallet that requires your user to authorise the payment with their bank. Deposits have a limit of 1000 amount_in_minor (10 GBP/EUR) in sandbox.

Before you begin

The deposits providers endpoint serves three purposes:

  • Tells you which banks are currently active (when a bank is temporarily unavailable, we hide them from this list until its service is restored).
  • Gives you the assets to build out a selection screen, for example, logos and display names.
  • Tells you the available schemes, auth flows, and input requirements for each provider.

To retrieve providers whose requirements you support, you must filter using the following query parameters:

FieldAvailable ValuesMandatoryDescription
auth_flow_typeredirect
embedded
MandatoryWill only return providers with schemes that support the listed auth flows.
account_typesort_code_account_number
iban
bban
nrb
MandatoryWill only return providers with schemes that support the listed account identifiers.
currencyISO 4217 currency codes
e.g. GBP,EUR
MandatoryWill only return providers with schemes that support the listed currencies.
countryISO 3166-1 alpha-2 country codes
e.g. GB,FR
OptionalWill only return providers from the listed countries.
additional_input_typetext
select
text_with_image
OptionalWill filter out any provider schemes that require additional_inputs field types not specified (including any on subsequent inputs as part of the embedded flow). If omitted, will only return provider schemes that have no required additional inputs.
release_channellive
public_beta
private_beta
OptionalWill filter out any providers that are not on the specified release channel (public_beta also includes all those in live, and private_beta also includes all those in public_beta). If omitted, will only return providers that are generally available (equivalent to live).

Each bank available will have the following fields:

FieldTypeDescription
provider_idstringThis is the provider ID that you will send us in the create payment request.
logo_urlstringThis is the address of the logo asset in SVG form.
display_namestringThis is a readable name for the provider.
countrystringThe ISO 3166-1 alpha-2 country code for the provider.
divisionsstring[]This array includes all divisions that are available on this provider, e.g. retail and business would indicate you can use this single provider to access both retail and business accounts.
deposit_schemesDepositScheme[]The array lists the available schemes the provider can use, within each is described the requirements for the fields on the Deposit initiation request.
release_stagestringThis indicates the product maturity of the provider. live and public_beta providers are visible to everyone, while private_beta providers must be enabled for the client_id provided in the query parameters to be visible.
Values: live, public_beta, private_beta.

📘

We recommend you query this endpoint every time you make a payment to ensure that you are always accessing the latest providers information. We are constantly working towards improving your experience with us by removing banks that are not currently available, adding banks as we expand our coverage, and updating banks' requirements.

  • DepositScheme
FieldTypeDescription
scheme_idstringA unique identifier for the scheme, shared across providers. This should be provided on the deposit.scheme_id field on the initiation request.
fee_options
(optional)
FeeOption[]If present, then fees are payable to make a payment on the scheme, and you must choose an option in this list when initiating a payment.
requirementsDepositRequirements[]Contains at least one set of requirements, one of which should be adhered to in order to create a valid initiation request for the scheme.
  • FeeOption
FieldTypeDescription
fee_option_idstringA unique identifier for the fee option, shared across providers. This should be provided on the deposit.fee_option_id field on the initiation request.
beneficiary_feestringA value to indicate if the beneficiary would pay any fees on the transaction, when using this fee option.
Values: free, payable, unknown
remitter_feestringA value to indicate if the remitter would pay any fees on the transaction, when using this fee option.
Values: free, payable, unknown
  • DepositRequirements

Each property in the requirements object corresponds to an identically named property on the initiation request for a Deposit.
The following sections detail the requirement types and how they should be interpreted in order to build a valid initiation request.

FieldChild FieldTypeDescription
auth_flow-AuthFlowRequirementsWhich auth flows are supported and what fields are required/available to initiate a payment for those flows.
depositcurrencyCurrencyRequirementsWhich currencies are supported.
depositbeneficiaryParticipantRequirementsWhich beneficiary details are required/supported.
depositremitter
(optional)
ParticipantRequirementsWhich remitter details are required/supported. If omitted, the scheme does not support receiving remitter details.
depositreferencesReferenceRequirementsWhich reference types are required/supported.
  • AuthFlowRequirements
FieldTypeDescription
typesstring[]A list of supported auth flow types.
Values: redirect,embedded.
redirect
(optional)
RedirectAuthFlowRequirementsWill be set if redirect is supported.
embedded
(optional)
EmbeddedAuthFlowRequirementsWill be set if embedded is supported.
  • RedirectAuthFlowRequirements
FieldTypeDescription
psu_ip_address_required
(optional)
booleanIndicates if auth_flow.psu_ip_address is required on the initiation request.
data_access_token_supported
(optional)
booleanIndicates if auth_flow.data_access_token can be provided on the initiation request, to maintain long lived consents across products (Data API and Payment API), where the provider only allows a single active consent across both AIS and PIS services.
additional_inputs
(optional)
AdditionalInputsAn optional dictionary of ID to additional inputs that must be collected from the end user to initiate a payment. These inputs should be provided using the same IDs in the auth_flow.additional_inputs string dictionary on the initiation request.
  • EmbeddedAuthFlowRequirements
FieldTypeDescription
additional_input_typesstring[]A list of additional input field types that may be returned during the embedded authorisation flow (not inclusive of those required on initiation below).
Values: text, text_with_image, select.
additional_inputs
(optional)
AdditionalInputsAn optional dictionary of ID to additional inputs that must be collected from the end user to initiate a payment. These inputs should be provided using the same IDs in the auth_flow.additional_inputs string dictionary on the initiation request.
  • CurrencyRequirements
FieldTypeDescription
supported_currenciesstring[]A list of ISO 4217 currency codes supported by the provider scheme.
  • ParticipantRequirements
FieldChild FieldTypeDescription
accounttypesstring[]A list of account types supported by the scheme.
Values: sort_code_account_number, iban, bban, nrb.
name
(optional)
-StringFieldRequirementsAn object detailing the requirements for the name, if omitted then setting the name on the initiation request is not supported for this scheme.
mandatory-boolIf a remitter is required. Not present on beneficiary as that is always mandatory.
  • ReferenceRequirements
FieldChild FieldTypeDescription
types-string[]A list of supported reference types.
Values: single,separate
single
(optional)
-StringFieldRequirementsWill be set if single is supported. Specifies the requirements for a single reference string for the payment.
separate
(optional)
beneficiaryStringFieldRequirementsWill be set if separate is supported. Specifies the requirements for the beneficiary reference string for the payment.
separate
(optional)
remitterStringFieldRequirementsWill be set if separate is supported. Specifies the requirements for the remitter reference string for the payment.
  • StringFieldRequirements
FieldTypeRequirement Description
mandatorybooleanThe corresponding field on the request is mandatory.
min_lengthintegerThe corresponding field on the request must be at least this many characters.
max_lengthintegerThe corresponding field on the request must be at most this many characters.
regexstringThe corresponding field on the request must match the regular expression.
formatstringA well known format to help you communicate to your client how the field will be validated.
Values: any, numerical, alphabetical, alphanumerical, email
  • AdditionalInputs

The additional_inputs object on responses is a dictionary of input IDs to an object describing the input required. The structure of the input object differs based on the type property, and can be one of the following:

Input TypeDescriptionCorresponding Request Value
textRequires the end user to enter a string valueThe string value the end user entered
text_with_imageDisplays an image to the end user and requires them to enter a string valueThe string value the end user entered
selectProvides a list of options for the end user to select fromThe id of the selected option
  • Text Input
FieldTypeDescription
typestringValue indicating the field type: text
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
sensitivebooleanIf the input is sensitive (should be masked in UI)
min_lengthintegerThe minimum length of the input text
max_lengthintegerThe maximum length of the input text
regexstringA regular expression the input text must match
formatstringA well known format, to facilitate being able to show useful prompts to the user.
Values: any, numerical, alphabetical, alphanumerical, email
{
  "some_input_id": {
    "type": "text",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "sensitive": false,
    "min_length": 5,
    "max_length": 15,
    "regex": "^[a-z ]{5,15}$",
    "format": "alphabetical"
  }
}
{
  "some_input_id": "entered value"
}
  • Text With Image Input
FieldTypeDescription
typestringValue indicating the field type: text_with_image
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
sensitivebooleanIf the input is sensitive (should be masked in UI)
min_lengthintegerThe minimum length of the input text
max_lengthintegerThe maximum length of the input text
regexstringA regular expression the input text must match
formatstringA well known format, to facilitate being able to show useful prompts to the user.
Values: any, numerical, alphabetical, alphanumerical, email
imageobjectAn image to display to the end user (for example, QR code).
The image object can be of two types, base64 or uri.
If type is base64, there will be a base64 property containing the base64 data and media_type.
If type is uri, there will be a uri property with a URI to a hosted copy of the image.
{
  "some_input_id": {
    "type": "text_with_image",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "sensitive": false,
    "min_length": 5,
    "max_length": 15,
    "regex": "^[a-z ]{5,15}$",
    "format": "alphabetical",
    "image": {
      "type": "base64",
      "base64": {
        "data":
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8vlr6PwAHHAK+MKsa+gAAAABJRU5ErkJggg==",
        "media_type": "image/png"
      }
    }
  }
}
{
  "some_input_id": "entered value"
}
  • Select Input
FieldTypeDescription
typestringValue indicating the field type: select
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
optionsSelectOption[]A list of id-display_text pairs to present to the end user as options (e.g. a drop down).
{
  "some_input_id": {
    "type": "select",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "options": [
      {
        "id": "option-a",
        "display_text": "First Option"
      },
      {
        "id": "option-b",
        "display_text": "Second Option"
      }
    ]
  }
}
{
  "some_input_id": "option-b"
}
  • SelectOption
FieldTypeDescription
idstringValue to be provided on the initiation request, if the option is selected
display_textstringText to describe the option
https://paydirect.truelayer-sandbox.com/v1/deposits/providers?auth_flow_type=redirect,embedded&account_type=sort_code_account_number,iban&additional_input_type=text,select&currency=GBP,EUR

You'll get a response like the following:

{
  "results": [
    {
      "provider_id": "ob-example",
      "logo_url": "https://truelayer-client-logos.s3-eu-west-1.amazonaws.com/banks/ob-example.svg",
      "display_name": "Example OB Bank",
      "country": "GB",
      "divisions": [ "retail", "business" ],
      "deposit_schemes": [
        {
          "scheme_id": "faster_payments_service",
          "requirements": [
            {
              "auth_flow": {
                "types": [ "redirect" ],
                "redirect": {
                  "data_access_token_supported": true
                }
              },
              "deposit": {
                "currency": {
                  "supported_currencies": [ "GBP" ]
                },
                "beneficiary": {
                  "account": {
                    "types": [ "sort_code_account_number" ],
                  },
                  "name": {
                    "mandatory": true,
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d ]{1,20}",
                    "format": "any"
                  }
                },
                "remitter": {
                  "mandatory": false,
                  "account": {
                    "types": [ "sort_code_account_number" ],
                  },
                  "name": {
                    "mandatory": false,
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d ]{1,20}",
                    "format": "any"
                  }
                },
                "references": {
                  "types": [ "single", "separate" ],
                  "single": {
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d \\.-]{1,20}",
                    "format": "any"
                  },
                  "separate": {
                    "beneficiary": {
                      "min_length": 1,
                      "max_length": 20,
                      "regex": "[\\w\\d \\.-]{1,20}",
                      "format": "any"
                    },
                    "remitter": {
                      "min_length": 1,
                      "max_length": 20,
                      "regex": "[\\w\\d \\.-]{1,20}",
                      "format": "any"
                    }
                  }
                }
              }
            }
          ]
        }
      ],
      "release_stage": "live"
    },
    {
      "provider_id": "eur-example",
      "logo": "https://truelayer-client-logos.s3-eu-west-1.amazonaws.com/banks/eur-example.svg",
      "display_name": "Example EUR Bank",
      "country": "DE",
      "divisions": [ "retail" ],
      "deposit_schemes": [
        {
          "scheme_id": "sepa_credit_transfer_instant",
          "fee_options": [
            {
              "fee_option_id": "remitter_payable",
              "beneficiary_fee": "free",
              "remitter_fee": "payable"
            },
            {
              "fee_option_id": "beneficiary_payable",
              "beneficiary_fee": "payable",
              "remitter_fee": "free"
            }
          ],
          "requirements": [
            {
              "auth_flow": {
                "types": [ "embedded" ],
                "embedded": {
                  "additional_input_types": [ "text" ],
                  "additional_inputs": {
                    "some-upfront-input": {
                      "type": "select",
                      "mandatory": true,
                      "options": [
                        {
                          "id": "option-a",
                          "display_text": "First Option"
                        },
                        {
                          "id": "option-b",
                          "display_text": "Second Option"
                        }
                      ]
                    }
                  }
                }
              },
              "deposit": {
                "currency": {
                  "supported_currencies": [ "EUR" ]
                },
                "beneficiary": {
                  "account": {
                    "types": [ "iban" ],
                  },
                  "name": {
                    "mandatory": true,
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d ]{1,20}",
                    "format": "any"
                  }
                },
                "remitter": {
                  "mandatory": true,
                  "account": {
                    "types": [ "iban" ],
                  },
                  "name": {
                    "mandatory": false,
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d ]{1,20}",
                    "format": "any"
                  }
                },
                "references": {
                  "types": [ "single" ],
                  "single": {
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d \\.-]{1,20}",
                    "format": "any"
                  }
                }
              }
            }
          ]
        }
      ],
      "release_stage": "live"
    }
  ]
}

Create a deposit

📘

You need to sign POST requests to /v1/users/deposits. Check our page on request signing to learn how to sign POST requests to PayDirect API endpoints.

The initiation request includes the following fields:

FieldTypeMandatoryDescription
depositDepositRequestDetailsMandatorySpecifies the details of the payment to be created.
auth_flowAuthFlowRequestDetailsMandatorySpecifies how the payment should be authorised.
webhook_uristringOptionalAn address to which payment webhooks with the status of the payment should be sent. Has to be https.
  • DepositRequestDetails
FieldTypeMandatoryDescription
user_iduuidMandatoryThe unique id of the user whose account you want to initiate the deposit from. The user id is generated client side. PayDirect will persist this user id and correlate transactions associated with this user id to deliver our services. All API calls involving the user in future should use the user id corresponding to the user.
deposit_iduuidMandatoryThe unique id of the payment you want to create. If two requests are received with the same id, only the first one will be processed.
amount_in_minornumberMandatoryThe amount, specified in terms of the fractional monetary unit of the payment currency, to be paid.
currencystringMandatoryThe ISO 4217 code of the currency for the payment.
provider_idstringMandatoryThe id of the provider, as given on our /providers endpoint.
scheme_idstringConditionalThe id of the scheme to make the payment over. This must be one of the schemes advertised by the provider on the /v1/deposits/providers endpoint. If omitted, the default value of faster_payments_service will be used.
fee_option_idstringConditionalThe id indicating the desired distribution of fees between the beneficiary and remitter. Must be a fee_option_id from one of the options advertised under that scheme on the /v1/deposits/providers endpoint. Should be omitted if there are no fee options (the scheme is free).
remitterParticipantDetailsOptionalThe details of the remitter sending the payment.
remitter_referencestringOptionalThe reference to appear on the remitters' statement.
  • ParticipantDetails
FieldTypeMandatoryDescription
accountAccountIdentifierDetailsMandatoryThe details of the account owned by the participant.
namestringConditionalThe name on the participant's account.
  • AccountIdentifierDetails
FieldTypeMandatoryDescription
typestringMandatoryThe type of account. Must be one of sort_code_account_number, iban, bban, or nrb. Check our /providers endpoint for details of what account types are supported by each provider.
sort_codestringMandatory if type is sort_code_account_number. Invalid otherwise.6 digit sort code (no spaces or dashes).
account_numberstringMandatory if type is sort_code_account_number. Invalid otherwise.8 digit account number.
ibanstringMandatory if type is iban. Invalid otherwise.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).
bbanstringMandatory if type is bban. Invalid otherwise.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.
nrbstringMandatory if type is nrb. Invalid otherwise.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.
  • AuthFlowRequestDetails
FieldTypeMandatoryDescription
typestringMandatoryThe type of authorisation flow. Must be redirect or embedded. Providers requiring additional authorisation flows may be available in future.
return_uristringMandatory if type is redirect. Invalid otherwise.The URI we will return the user to after authorising the payment. When the user is redirected to this URI, we will append a deposit_id query parameter specifying the payment id and a type query parameter with value deposit.
psu_ip_addressstringConditional if type is redirect. Invalid otherwise.The IP address of the end user.
data_access_tokenstringOptional if type is redirect. Invalid otherwise.If the provider only allows a single active consent across both AIS and PIS services, in order to prevent invalidating an existing AIS consent, you can pass the data access token on this field, and we will preserve the data consent when requesting authorisation for the payment.
additional_inputsdictionary<string, string>ConditionalA dictionary of additional values required on a per-provider basis. Check our /providers endpoint for details of the providers that require these.

Make a POST /users/deposits request:

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     -H "X-TL-Signature: ${signature}" \
     --data '{
  "user_id": "c17cae3a-98d1-44cc-aebe-8bcbffd57280",
  "deposit": {
    "deposit_id": "dcc3e785-76d3-415c-8bd7-553f17f49c4a",
    "provider_id": "eg-provider",
    "amount_in_minor": 120000,
    "currency": "GBP",
    "remitter": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "987654",
        "account_number": "98765432"
      },
      "name": "Mike Smith"
    },
    "remitter_reference": "abcdefg123"
  },
  "auth_flow": {
    "type": "redirect",
    "return_uri": "https://client.app.com/payment_return"
  }
}' \
https://paydirect.truelayer.com/v1/users/deposits

You'll get a response like the following:

{
  "result": {
    "deposit": {
      "deposit_id": "dcc3e785-76d3-415c-8bd7-553f17f49c4a",
      "status": "initiated",
      "initiated_at": "2020-10-13T10:01:23.381Z",
      "provider_id": "eg-provider",
      "scheme_id": "payment_scheme",
      "fee_option_id": "split_fee",
      "amount_in_minor": 120000,
      "currency": "GBP",
      "remitter": {
        "account": {
          "type": "sort_code_account_number",
          "sort_code": "987654",
          "account_number": "98765432"
        },
        "name": "Mike Smith"
      },
      "references": {
        "remitter": "FS-1000001"
      }
    },
    "auth_flow": {
      "type": "redirect",
      "uri": "https://www.eg-provider.com/authorize?token=0f9e8d7c",
      "expiry": "2020-11-03T23:00:00.000Z"
    }
  }
}

Handle the initiation request response

The response from the /users/deposits/ endpoint, shown above, returns the following fields:

FieldTypeDescription
depositDepositResponseDetailsContains the details of the payment. This is a superset of the DepositRequestDetails object. Note this is the same object as that which will be returned on the GET /v1/users/{userId}/deposits/{id} endpoint.
auth_flowAuthFlowResponseDetailsThis provides information on how to have the end user authorise the payment, and will differ in structure based on the authorisation flow.
  • DepositResponseDetails

This contains the following fields in addition to those listed in the DepositRequestDetails section:

FieldTypeDescription
initiated_atstringThe time the payment was initiated, in UTC formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ).
statusstringThe status of the payment. For newly initiated payments, this will be initiated.
  • AuthFlowResponseDetails

If the provider uses a redirect authorisation flow, the auth_flow object on the response will have the following fields:

FieldTypeDescription
typestringValue indicating this is a redirect authorisation flow: redirect
uristringThe URI for the end user to authorise the payment in the bank's UI.
expiry
(optional)
stringAn expiry time, if one is known, after which the URI to authorise the payment will become invalid. In UTC, formatted as an ISO 8601 string (YYYY-MM-DDThh:mm:ss.sssZ).
{
  "type": "redirect",
  "uri": "https://example.com",
  "expiry": "2020-11-03T23:00:00.000Z"
}

After creating the payment, you will need to redirect the user to the authorisation page specified by uri.

Deposit statuses

Below are the various states a deposit can be in. You can query the status of your deposit using the GET v1/users/{user_id}/deposits/{deposit_id} endpoint. PayDirect will send webhook events for status transitions.

StatusTerminal?Description
initiatedNoThe payment resource corresponding to the deposit has been created, but the user has not yet authorised the payment. The initial API response will always have this status if the API call is successful.
cancelledYesThe user has cancelled the deposit payment using the bank portal. This may also happen for some bank UIs if the payer clicks the “Back” button in their browser
authorisation_failedYesThe user attempted to authorise the deposit payment with the bank, but failed to do so successfully
executingNoThe user has successfully authorised the deposit payment using the bank portal, but the payment has not yet executed.
rejectedYesThe user authorised the deposit payment, but the bank rejected it after this.
executedNoThe funds have left the remitter’s account and will arrive your merchant account.
expiredYesThe deposit payment was not authorised within the expiry of the initiation.
settledYesThe deposit payment has settled into your merchant account.

Get deposit example

You can retrieve the details and status of a deposit at any time using the deposit_id.

curl -H "Authorization: Bearer ${access_token}" \
https://paydirect.truelayer-sandbox.com/v1/users/${userId}/deposits/${depositId}
{
  "result": {
    "deposit_id": "8361f601-cc39-43f5-a761-89ae54d7440e",
    "initiated_at": "2021-03-09T17:04:27.58",
    "status": "settled",
    "provider_id": "mock-payments",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "040662",
        "account_number": "00003151"
      },
      "name": "Jane Doe"
    },
    "remitter": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "040662",
        "account_number": "00002723"
      },
      "name": "JANE DOE"
    },
    "references": {
      "type": "single",
      "reference": "VH/4LH4Y1DJ8LCA67Z"
    },
    "settled": {
      "account_id": "5156e5af-7bf2-49a4-96b3-7fde5ec8ddfe",
      "transaction_id": "af59237f-fa61-476a-aad6-66a6c13cd40b",
      "settled_at": "2021-03-09T17:05:32.427Z"
    }
  }
}

Once a deposit has been settled, we include the settled object which contains additional information regarding the deposit.

FieldTypeDescription
settled.account_iduuidThe unique TrueLayer generated id of the account the deposit came from.
settled.transaction_iduuidThe unique id of the transaction that will correspond to the transaction_id in the transactions returned by the /transactions endpoint.
settled.settled_atTimestampThe date and time the deposit settled into the account.

Did this page help you?