Migration from v1 to v2

Depending on your usage of the v1 single-immediate-payments endpoint, you may be able to migrate to v2 to take advantage of any new features.

You can only migrate to v2 if you specify direct_bank_link as true on your v1 requests. You do not make any use of our provider selection, payment details, or handoff screens. The v2 single-immediate-payments endpoints do not currently support these use cases.

UK Single Immediate Payments Providers Requests

https://pay-api.truelayer.com/providers?capability=SingleImmediatePayment
https://pay-api.truelayer.com/v2/single-immediate-payments-providers?client_id=myclient-123456&auth_flow_type=redirect&account_type=sort_code_account_number&currency=GBP&country=GB

To retrieve providers from the new v2 Single Immediate Payments Providers API, you must provide query parameters specifying what features you support. For UK providers available on v1, that is the equivalent of these filters:

FieldValueDescription
client_idYour client IDRequired for verifying access to providers.
auth_flow_typeredirectWill only return providers with schemes that support the redirect auth flow.
account_typesort_code_account_numberWill only return providers with schemes that support sort code with account numbers as account identifiers.
currencyGBPWill only return providers with schemes that support GBP payments.
countryGBWill only return providers from the UK.

International Single Immediate Payments Providers Requests

https://pay-api.truelayer.com/providers?capability=SingleImmediatePayment&countryCode=FR&clientId=myclient-123456
https://pay-api.truelayer.com/v2/single-immediate-payments-providers?client_id=myclient-123456&auth_flow_type=redirect&account_type=iban&currency=EUR&country=FR&additional_input_type=text,select

For international providers available on v1, that is the equivalent of these filters:

FieldValueDescription
client_idYour client IDRequired for verifying access to providers.
auth_flow_typeredirectWill only return providers with schemes that support the redirect auth flow.
account_typeibanWill only return providers with schemes that support IBANs as account identifiers.
currencyEURWill only return providers with schemes that support EUR payments.
countryfor example, FRWill only return providers from the chosen country, for example, France.
additional_input_typetext,selectWill filter out any provider schemes that require additional_inputs field types not are not text or select. These correspond to the FreeInputField and SingleChoiceField auth inputs on the v1 providers API.

Single Immediate Payments Providers Response

{
  "results": [{
    "id": "ob-example",
    "logo": "https://the.website/path/to/logo.png",
    "icon": "https://the.website/path/to/icon.png",
    "displayable_name": "Example Provider",
    "main_bg_color": "#000000",
    "supports_app_to_app": false,
    "country_code": "GB",
    "divisions": [
      "retail"
    ],
    "steps": [
      ...
    ]
  }]
}
{
  "results": [{
    "provider_id": "ob-example",
    "logo_url": "https://the.website/path/to/logo.png",
    "display_name": "Example Provider",
    "country": "GB",
    "divisions": [
      "retail"
    ],
    "single_immediate_payment_schemes": [
      {
        "scheme_id": "faster_payments_service",
        "requirements": [
          {
            "auth_flow": {
              "types": ["redirect"],
              "redirect": {
                "additional_inputs": {
                  ...
                }
              }
            },
            "single_immediate_payment": {
              ...
            }
          }
        ]
      }
    ]
  }]
}

The v2 response has a slightly different structure, along with a new schemes / requirements section.

v1 parameterv2 parameterComment
idprovider_id
logologo_url
iconn/aNot available on v2
displayable_namedisplay_name
main_bg_colorn/aNot available on v2
supports_app_to_appn/aNot available on v2
country_codecountry
divisionsdivisions
auth_inputsschemes[].requirements[].auth_flow.redirect.additional_inputsThe inputs have a different structure documented above in the AdditionalInputs section.

UK Single Immediate Payments Requests

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "remitter_provider_id": "ob-provider",
  "amount": 100,
  "currency": "GBP",
  "beneficiary_sort_code": "234567",
  "beneficiary_account_number": "23456789"
  "beneficiary_name": "Financial Services Ltd",
  "remitter_sort_code": "987654",
  "remitter_account_number": "98765432",
  "remitter_name": "Mike Smith",
  "beneficiary_reference": "FinServ-1a2b3c4d",
  "remitter_reference": "FS-1000001",
  "direct_bank_link": true,
  "redirect_uri": "https://client.app.com/payment_return",
  "webhook_uri": "https://client.app.com/simp/webhook"
}' \
https://pay-api.truelayer.com/single-immediate-payments
curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "single_immediate_payment": {
    "single_immediate_payment_id": "4b794546-780c-4bab-854b-ee0728828d3e",
    "provider_id": "ob-provider",
    "scheme_id": "faster_payments_service",
    "amount_in_minor": 100,
    "currency": "GBP",
    "beneficiary": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "234567",
        "account_number": "23456789"
      },
      "name": "Financial Services Ltd"
    },
    "remitter": {
      "account": {
        "type": "sort_code_account_number",
        "sort_code": "987654",
        "account_number": "98765432"
      },
      "name": "Mike Smith"
    },
    "references": {
      "type": "separate",
      "beneficiary": "FinServ-1a2b3c4d",
      "remitter": "FS-1000001"
    }
  },
  "auth_flow": {
    "type": "redirect",
    "return_uri": "https://client.app.com/payment_return"
  },
  "webhook_uri": "https://client.app.com/simp/webhook"
}' \
https://pay-api.truelayer.com/v2/single-immediate-payment-initiation-requests

To adapt an existing integration of UK single immediate payments to use v2 of our single immediate payments API, map the following fields on your requests:

v1 parameterv2 parameterComment
n/asingle_immediate_payment.single_immediate_payment_idv2 requires that a payment id is supplied on the initiation request
remitter_provider_idsingle_immediate_payment.provider_id
n/asingle_immediate_payment.scheme_idv2 requires the scheme to be specified, which is faster_payments_service in the UK
amountsingle_immediate_payment.amount_in_minor
currencysingle_immediate_payment.currency
n/asingle_immediate_payment.beneficiary.account.typeSet this to sort_code_account_number
beneficiary_sort_codesingle_immediate_payment.beneficiary.account.sort_code
beneficiary_account_numbersingle_immediate_payment.beneficiary.account.account_number
beneficiary_namesingle_immediate_payment.beneficiary.name
n/asingle_immediate_payment.remitter.account.typeIf remitter account is specified, set this to sort_code_account_number
remitter_sort_codesingle_immediate_payment.remitter.account.sort_code
remitter_account_numbersingle_immediate_payment.remitter.account.account_number
remitter_namesingle_immediate_payment.remitter.name
n/asingle_immediate_payment.referencesSet this to separate
beneficiary_referencesingle_immediate_payment.references.beneficiary
remitter_referencesingle_immediate_payment.references.remitter
direct_bank_linkn/aMust be true in order to migrate to v2
n/aauth_flow.typeSet this to redirect
redirect_uriauth_flow.return_uri
webhook_uriwebhook_uri

Note that the new endpoint path is now /v2/single-immediate-payment-initiation-requests.

International Single Immediate Payments Requests (Private Beta)

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "remitter_provider_id": "stet-french-bank",
  "amount": 100,
  "currency": "EUR",
  "beneficiary_iban": "FR2222222222222222222222B02",
  "beneficiary_name": "Financial Services Ltd",
  "remitter_iban": "FR1111111111111111111111A01",
  "remitter_name": "Mike Smith",
  "beneficiary_reference": "FinServ-1a2b3c4d",
  "remitter_reference": "FS-1000001",
  "direct_bank_link": true,
  "redirect_uri": "https://client.app.com/payment_return",
  "auth_inputs": {
    "branch_id": "stet-french-bank-branch-4"
  },
  "webhook_uri": "https://client.app.com/simp/webhook"
}' \
https://pay-api.truelayer.com/single-immediate-payments
curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "single_immediate_payment": {
    "single_immediate_payment_id": "4b794546-780c-4bab-854b-ee0728828d3e",
    "provider_id": "stet-french-bank",
    "scheme_id": "sepa_credit_transfer_instant",
    "amount_in_minor": 100,
    "currency": "EUR",
    "beneficiary": {
      "account": {
        "type": "iban",
        "iban": "FR2222222222222222222222B02"
      },
      "name": "Financial Services Ltd"
    },
    "remitter": {
      "account": {
        "type": "iban",
        "iban": "FR1111111111111111111111A01"
      },
      "name": "Mike Smith"
    },
    "references": {
      "type": "separate",
      "beneficiary": "FinServ-1a2b3c4d",
      "remitter": "FS-1000001"
    }
  },
  "auth_flow": {
    "type": "redirect",
    "return_uri": "https://client.app.com/payment_return",
    "additional_inputs": {
      "branch_id": "stet-french-bank-branch-4"
    }
  },
  "webhook_uri": "https://client.app.com/simp/webhook"
}' \
https://pay-api.truelayer.com/v2/single-immediate-payment-initiation-requests

To adapt an existing integration of international single immediate payments to use v2 of our single immediate payments API, map the following fields on your requests:

v1 parameterv2 parameterComment
n/asingle_immediate_payment.single_immediate_payment_idv2 requires that a payment id is supplied on the initiation request
remitter_provider_idsingle_immediate_payment.provider_id
n/asingle_immediate_payment.scheme_idv2 requires the scheme to be specified, which you should choose from those available on the v2 providers API
n/asingle_immediate_payment.fee_option_idv2 requires a fee option to be specified, if fee options are listed on the scheme on the v2 providers API
amountsingle_immediate_payment.amount_in_minor
currencysingle_immediate_payment.currency
n/asingle_immediate_payment.beneficiary.account.typeSet this to iban
beneficiary_ibansingle_immediate_payment.beneficiary.account.iban
beneficiary_namesingle_immediate_payment.beneficiary.name
n/asingle_immediate_payment.remitter.account.typeIf remitter account is specified, set this to iban
remitter_ibansingle_immediate_payment.remitter.account.iban
remitter_namesingle_immediate_payment.remitter.name
n/asingle_immediate_payment.referencesSet this to separate
beneficiary_referencesingle_immediate_payment.references.beneficiary
remitter_referencesingle_immediate_payment.references.remitter
direct_bank_linkn/aMust be true in order to migrate to v2
n/aauth_flow.typeSet this to redirect
redirect_uriauth_flow.return_uri
auth_inputsauth_flow.additional_inputs
webhook_uriwebhook_uri

Note that the new endpoint path is now /v2/single-immediate-payment-initiation-requests.

Single Immediate Payments Response (Private Beta)

{
  "results": [{
    "simp_id": "4b794546-780c-4bab-854b-ee0728828d3e",
    "auth_uri": "https://bank.com/auth-uri",
    "status": "new",
    "created_at": "2020-01-01T12:00:00.0000000+00:00",
    "remitter_provider_id": "ob-provider",
    "amount": 100,
    "currency": "GBP",
    "beneficiary_name": "Financial Services Ltd",
    "beneficiary_sort_code": "234567",
    "beneficiary_account_number": "23456789",
    "remitter_name": "Mike Smith",
    "remitter_sort_code": "987654",
    "remitter_account_number": "98765432",
    "beneficiary_reference": "FinServ-1a2b3c4d",
    "remitter_reference": "FS-1000001",
    "redirect_uri": "https://client.app.com/payment_return",
    "webhook_uri": "https://client.app.com/simp/webhook"
  }],
  "status": "succeeded"
}
{
  "result": {
    "single_immediate_payment": {
      "single_immediate_payment_id": "4b794546-780c-4bab-854b-ee0728828d3e",
      "status": "initiated",
      "initiated_at": "2020-01-01T12:00:00.0000000",
      "provider_id": "ob-provider",
      "amount_in_minor": 100,
      "currency": "GBP",
      "beneficiary": {
        "account": {
          "type": "sort_code_account_number",
          "sort_code": "234567",
          "account_number": "23456789"
        },
        "name": "Financial Services Ltd"
      },
      "remitter": {
        "account": {
          "type": "sort_code_account_number",
          "sort_code": "987654",
          "account_number": "98765432"
        },
        "name": "Mike Smith"
      },
      "references": {
        "type": "separate",
        "beneficiary": "FinServ-1a2b3c4d",
        "remitter": "FS-1000001"
      }
    },
    "auth_flow": {
      "type": "redirect",
      "uri": "https://bank.com/auth-uri",
      "expiry": "2020-09-30T12:33:55Z"
    },
    "webhook_uri": "https://client.app.com/simp/webhook"
  }
}

The same information that was returned in v1 is returned in v2 with a slightly different structure, along with some additional properties.

  • The properties that are intrinsic to the single immediate payment are now found nested under a single_immediate_payment object.
  • The information to allow the user to authorise the payment is nested under an auth_flow object - in this case the URI to redirect the user to where they can authorise the payment.
v1 parameterv2 parameterComment
results[0]result.single_immediate_paymentThe payment object now exists under result.single_immediate_payment. Note in v2, this has the same structure as the payment on the initiation request.
results[0].auth_uriresult.auth_flow.uriThe uri to redirect the user to for them to authorise the payment exists in the result.auth_flow object of the response.

Handle the redirect authorisation flow

📘

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

For payments initiated through our v1 /single-immediate-payments endpoint, we return the user to the URI specified by redirect_uri with a payment_id query parameter.

Payments initiated through our /v2/single-immediate-payment-initiation-requests will return the user to the URI specified by auth_flow.return_uri with a single_immediate_payment_id query parameter, specifying the payment id, and a type query parameter, specifying the payment type. Currently the only value we will send for type is single_immediate_payment, however further payment types will be available in the future.


Did this page help you?