Introduction
Open banking enables your customers to send funds from their bank account to their Customate wallet.
You will receive a URI to redirect your user to – this will be the URI of the bank.
Once they have made the payment, they will be redirected to a URL of your choice (typically a page on your site).
Funds will be transferred almost immediately.
Required information for the endpoint, open_banking_to_wallet_payments
- amount, in pence or cents
- country (we currently support the UK and Spain – more countries to follow)
- currency (GBP or EUR – more currencies to follow)
- bank (provider) ID (see below)
- bank account details for Euro payments only (payer IBAN)
- webhook URI (an endpoint on your site which will receive updates of the payment’s status)
Optional information
- description (payer’s reference)
- redirect URL (where the user will be redirected to after confirming or cancelling a payment)
- payer’s name
- beneficiary’s name
- metadata (useful for storing client-specific information, e.g. your payment ID)
Specifying the bank
You will need to show a list of banks (providers) to your user and then supply the provider ID to open_banking_to_wallet_payments.
We recommend setting payer_name to your user’s name and beneficiary_name to either your company or that of a third party.
If you don’t specify them, payer_name will be set to “Payer” and beneficiary_name will be set to “Customate”.
Example JSON request
{
"amount": 10000,
"description": "Deposit for Flat 1",
"country": "GB",
"currency": "GBP",
"webhook_uri": "https://www.yoursite.com/openbankingwebhook",
"redirect_url": "https://www.yoursite.com/payments",
"metadata": {
"your_payment_id": "1234567890"
},
"provider_id": "ob-sandbox-natwest",
"payer_name": "Mr Tenant",
"beneficiary_name": "Mrs Landlord"
}
The only provider (bank) in the sandbox, is Natwest, ID: ob-sandbox-natwest.
Example response
{
"data": {
"type": "payments",
"id": "da1e5655-d145-46f8-af3a-a52d90a0ca22",
"attributes": {
"currency": "GBP",
"data": {
"amount": 10000,
"description": "Deposit for Flat 1"
},
"metadata": {
"webhook_uri": "https://www.yoursite.com/openbankingwebhook",
"redirect_url": "https://www.yoursite.com/payments",
"uri": "https://natwest.com/as/oauth2?client_id=bc8...",
"country": "GB",
"metadata": {
"client_internal_id": "d2f148cf-901c-4fee-8792-21016da755a0"
}
},
"scenario": "OpenBankingToWallet",
"status": "PENDING",
"walletId": "d99bf180-2c3f-498f-a557-cd9c9272f13e"
},
"relationships": {
"recipient": {
"data": {
"type": "payees",
"id": "5f65a7a4-4929-4a03-a1ec-d6ff65987095"
}
}
}
}
}
Supported countries and banks
In production, this is the list of provider IDs and names for UK banks:
'ob-aib-corporate', 'AIB Corporate', 'ob-boi', 'Bank of Ireland', 'ob-bos', 'Bank of Scotland', 'ob-bos-business', 'Bank of Scotland Business', 'ob-barclays', 'Barclays', 'ob-barclays-business', 'Barclays Business', 'ob-danske', 'Danske Personal', 'ob-danske-business', 'Danske Business', 'ob-first-direct', 'First Direct', 'ob-halifax', 'Halifax', 'ob-hsbc', 'HSBC', 'ob-hsbc-business', 'HSBC Business', 'ob-lloyds', 'Lloyds', 'ob-lloyds-business', 'Lloyds Business', 'ob-ms', 'M&S', 'ob-monzo', 'Monzo', 'ob-nationwide', 'Nationwide', 'ob-natwest', 'Natwest', 'ob-natwest-business', 'NatWest Business', 'ob-rbs', 'RBS', 'ob-rbs-business', 'RBS Business', 'ob-revolut', 'Revolut', 'ob-santander', 'Santander', 'oauth-starling', 'Starling', 'ob-tesco', 'Tesco', 'ob-tsb', 'TSB', 'ob-ulster', 'Ulster Bank'
List of provider IDs and names for Spanish banks:
'xs2a-redsys-banco-santander', 'Banco Santander', 'x2sa-redsys-bbva', 'BBVA', 'x2sa-redsys-caixa', 'Caixa', 'x2sa-redsys-banco-sabadell', 'Banco de Sabadell', 'x2sa-redsys-bankia', 'Bankia', 'ob-revolut-es', 'Revolut Spain'
You can either display banks in a <select> or create a list of images/icons (of the banks).
To get these images, we’ve created an endpoint, open_banking_providers. Use either the logo_url or icon_url .
e.g. GET open_banking_providers?currency=GBP&country=GB or GET open_banking_providers?currency=EUR&country=ES
The JSON returned for the one provider in the sandbox:
{
"items": [
{
"provider_id": "ob-natwest",
"logo_url": "https://logos.aws.com/banks/natwest.svg",
"icon_url": "https://icons.aws.com/banks/ob-natwest-icon.svg",
"display_name": "Natwest",
"country": "GB"
}
]
}
Payment status
The payment will be pending until the user and bank actions it.
Your webhook will receive a notification when the payment completes.
Status will be one of SUCCESS, CANCELED or FAILED. For failed payments (typically when rejected by the bank), an error message will be set.
Example webhook data for a successful payment of £100.00
{
"status": "SUCCESS",
"amount": 10000,
"description": "Deposit for Flat 1",
"currency": "GBP",
"country": "GB",
"actual_balance": 50000,
"clients_ref": "1234567890",
"payment_id": "41b20034-fdca-4069-a7e4-e00040fd6918",
"payee_id": "5f65a7a4-4929-4a03-a1ec-d6ff65987095",
"funding_source_id": "5d4d80c3-c11e-515e-b1ab-9b2e9196384a",
"message": ""
}
Example webhook for a cancelled payment of £100.00
{
"status": "CANCELED",
"amount": 10000,
"description": "Deposit for Flat 1",
"currency": "GBP",
"country": "GB",
"actual_balance": 50000,
"clients_ref": "1234567890",
"payment_id": "41b20034-fdca-4069-a7e4-e00040fd6918",
"payee_id": "5f65a7a4-4929-4a03-a1ec-d6ff65987095",
"funding_source_id": "5d4d80c3-c11e-515e-b1ab-9b2e9196384a",
"message": ""
}
Example webhook for a failed payment of £100.00
{
"status": "FAILED",
"amount": 10000,
"description": "Deposit for Flat 1",
"currency": "GBP",
"country": "GB",
"actual_balance": 50000,
"clients_ref": "1234567890",
"payment_id": "41b20034-fdca-4069-a7e4-e00040fd6918",
"payee_id": "5f65a7a4-4929-4a03-a1ec-d6ff65987095",
"funding_source_id": "5d4d80c3-c11e-515e-b1ab-9b2e9196384a",
"message": "The payment was rejected by the bank"
}
Timings for money into a customate wallet using open banking pulling money from an external bank account
This scenario is used to load funds into a Customate wallet from an external bank account requiring the payer to validate the transaction with their external bank in real time. Our banking partner will facilitate the pull of the specified amount money from an external bank account (details that we don’t see because this is done within the user’s bank portal) and in response to a successful instruction from our banking partner, we will add specified amount (less fee) to user’s Customate wallet. Customates bank partners have no cut-off times for using this scenario, meaning that this transaction can be used 24/7. However, real time execution may not be met for payments held up for any compliance by the sending bank, lack of funds, incorrect credentials, or other internal policy reasons (e.g., limits established by the payer’s bank).
Expected outcomes
- Payer will enter the input data required and Customate will call the banking partner, putting the payment in a PENDING state until actioned by the payer via their external bank portal, the Customate wallet is not yet credited as transaction is not set to SUCCESS at this time. There is no time limit for the transaction to remain in this state as Customate awaits further information from the banking partner regarding the transaction and therefore theoretically could remain in this state indefinitely.
- When the payer correctly approves the payment via their external bank portal and the external bank acknowledges the transaction as valid, the status of the transaction is set to SUCCESS within 15 seconds and the Customate wallet is credited with the amount less any fee.
- If the input data is invalid or the payer failed to authorise the payment with the external bank or the payment was rejected by the bank, or an unexpected status was received from our banking partner, then the status is set to FAILED within 15 seconds, the Customate wallet is not credited as transaction does not achieve SUCCESS.
- In the scenario where an OB payment is held up by fraud by the bank, but is subsequently released by the bank, the payment remains as PROCESSING (even though payment may have arrived with Customate’s bank). There is no timeline on when this webhook is updated by the sending bank and therefore how long a user is expected to wait until funds are credited in their Customate wallet. Once this occurs the payment switches to SUCCESS.
- If the payer cancels the payment, the status is set to CANCELED within 15 seconds, the Customate wallet is not credited as transaction does not achieve SUCCESS.
Scenario 1: Money in from a bank sent during UK business day
1 – user sent £2.13 from external bank to wallet at 02:05:53 UTC Tuesday 7th Sep.
Webhook:
{
"items": [
{
"id": "82d6c9ca-7d8b-4abd-ba14-dd1b12c92e99",
"type": "payment.updated",
"creation_datetime": "2021-09-07T02:05:53.888871+00:00",
"data": {
"status": "pending",
"metadata": {
"webhook_uri": "https://webhook.site/8d535ebf-4797-435b-8c1c-48b83650fdbe",
"redirect_url": "https://app.gocustomate.com/",
"country": "GB",
"metadata": {
"clients_ref": "123456789"
},
"provider_id": "ob-hsbc",
"scheme_id": "faster_payments_service",
"remitter_name": "Payer",
"remitter_iban": "None",
"beneficiary_name": "Customate",
"additional_inputs": {},
"uri": "https://ob.hsbc.co.uk/obie/open-banking/v1.1/oauth2/authorize?client_id=3132da35-d570-4004-a46f-cb1c2d23f4f0&request=eyJhbGciOiJQUzI1NiIsImtpZCI6IjNxYnBNZGpUNGxBVXl3VVFjVk9GeWlfQmgtWSJ9.eyJhdWQiOiJodHRwczovL2FwaS5vYi5oc2JjLmNvLnVrIiwibmJmIjoxNjMwOTgwMzIzLCJpc3MiOiIzMTMyZGEzNS1kNTcwLTQwMDQtYTQ2Zi1jYjFjMmQyM2Y0ZjAiLCJleHAiOjE2MzA5ODA5NTMsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwiY2xpZW50X2lkIjoiMzEzMmRhMzUtZDU3MC00MDA0LWE0NmYtY2IxYzJkMjNmNGYwIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9jb25uZWN0LnRydWVsYXllci5jb20vcmVkaXJlY3Qvb3BlbmJhbmtpbmciLCJzY29wZSI6Im9wZW5pZCBwYXltZW50cyIsInN0YXRlIjoiMmRjZjI3Y2EtMjBlNi00ZTEzLWE3N2MtZTViM2I4NmQzYTg3Iiwibm9uY2UiOiI0M2IyYzBhNi1kZTcxLTQwZWEtOTZkYy01YjYyZTk1NzkwZGYiLCJtYXhfYWdlIjo4NjQwMCwiY2xhaW1zIjp7InVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6ImMxM2NhYjIwLTEwOWMtNDJmOS1hZDg0LTIzZDMxOGZhNjgxZCIsImVzc2VudGlhbCI6dHJ1ZX19LCJpZF90b2tlbiI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJjMTNjYWIyMC0xMDljLTQyZjktYWQ4NC0yM2QzMThmYTY4MWQiLCJlc3NlbnRpYWwiOnRydWV9LCJhY3IiOnsiZXNzZW50aWFsIjp0cnVlLCJ2YWx1ZXMiOlsidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwidXJuOm9wZW5iYW5raW5nOnBzZDI6Y2EiXX19fSwiYWNyX3ZhbHVlcyI6InVybjpvcGVuYmFua2luZzpwc2QyOnNjYSB1cm46b3BlbmJhbmtpbmc6cHNkMjpjYSIsImp0aSI6Ijk2YjEzNmIwLWUifQ.ACbQdCPFZDKmFT4DkvJCGJBskWCoNGOcLlnHhBL3mBdUK5qexoDTp-cRcAj8jQS5zu4Hokr3V6T1LO5438kFQFPIjKo_iSDPOfy877WNfGt-_s4uNe6XZVLTHjScTA8ERJaQmpZ7yNVrf5L8m2TsBFgjRDoiCQKKmKkgSvb1w6-jCzQggnTScYk80Or-2G2lf0APsaAHP_iW6DBRnhdaCtXN9C1GcqCXVqXBWIu9NT59GLBo8H0WhGJWZtnIb0ACxgvEbQvR8yaQMzdRoWuRI1VQkeMowna4oPco6YUlAuTANTaL8TYerSZHLzNfsCB003lZnIkGvpTmo_-Ecfa8sQ&state=2dcf27ca-20e6-4e13-a77c-e5b3b86d3a87&nonce=43b2c0a6-de71-40ea-96dc-5b62e95790df&scope=openid%20payments&response_type=code%20id_token&redirect_uri=https%3A%2F%2Fconnect.truelayer.com%2Fredirect%2Fopenbanking"
},
"scenario": "OpenBankingToWallet",
"error_code": null,
"error_message": null,
"closing_balance": 56475,
"funding_source": {
"id": "32db45e9-959b-dcae-c7ed-d0c5770970da"
},
"payee": {
"id": "e07648f2-0900-4d7c-9f41-973b9daf3430"
},
"id": "6f85b636-1834-4f86-8371-d9a47260d99c",
"schedule": {
"id": null
},
"profile": {
"id": "d871c453-18fe-497e-a84a-01b0f14d7a7c"
}
}
},
{
"id": "ccb97db4-b191-46b2-a5b0-73761795c0b3",
"type": "payment.updated",
"creation_datetime": "2021-09-07T02:05:53.899395+00:00",
"data": {
"status": "pending",
"metadata": {
"webhook_uri": "https://webhook.site/8d535ebf-4797-435b-8c1c-48b83650fdbe",
"redirect_url": "https://app.gocustomate.com/",
"country": "GB",
"metadata": {
"clients_ref": "123456789"
},
"provider_id": "ob-hsbc",
"scheme_id": "faster_payments_service",
"remitter_name": "Payer",
"remitter_iban": "None",
"beneficiary_name": "Customate",
"additional_inputs": {},
"uri": "https://ob.hsbc.co.uk/obie/open-banking/v1.1/oauth2/authorize?client_id=3132da35-d570-4004-a46f-cb1c2d23f4f0&request=eyJhbGciOiJQUzI1NiIsImtpZCI6IjNxYnBNZGpUNGxBVXl3VVFjVk9GeWlfQmgtWSJ9.eyJhdWQiOiJodHRwczovL2FwaS5vYi5oc2JjLmNvLnVrIiwibmJmIjoxNjMwOTgwMzIzLCJpc3MiOiIzMTMyZGEzNS1kNTcwLTQwMDQtYTQ2Zi1jYjFjMmQyM2Y0ZjAiLCJleHAiOjE2MzA5ODA5NTMsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwiY2xpZW50X2lkIjoiMzEzMmRhMzUtZDU3MC00MDA0LWE0NmYtY2IxYzJkMjNmNGYwIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9jb25uZWN0LnRydWVsYXllci5jb20vcmVkaXJlY3Qvb3BlbmJhbmtpbmciLCJzY29wZSI6Im9wZW5pZCBwYXltZW50cyIsInN0YXRlIjoiMmRjZjI3Y2EtMjBlNi00ZTEzLWE3N2MtZTViM2I4NmQzYTg3Iiwibm9uY2UiOiI0M2IyYzBhNi1kZTcxLTQwZWEtOTZkYy01YjYyZTk1NzkwZGYiLCJtYXhfYWdlIjo4NjQwMCwiY2xhaW1zIjp7InVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6ImMxM2NhYjIwLTEwOWMtNDJmOS1hZDg0LTIzZDMxOGZhNjgxZCIsImVzc2VudGlhbCI6dHJ1ZX19LCJpZF90b2tlbiI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJjMTNjYWIyMC0xMDljLTQyZjktYWQ4NC0yM2QzMThmYTY4MWQiLCJlc3NlbnRpYWwiOnRydWV9LCJhY3IiOnsiZXNzZW50aWFsIjp0cnVlLCJ2YWx1ZXMiOlsidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwidXJuOm9wZW5iYW5raW5nOnBzZDI6Y2EiXX19fSwiYWNyX3ZhbHVlcyI6InVybjpvcGVuYmFua2luZzpwc2QyOnNjYSB1cm46b3BlbmJhbmtpbmc6cHNkMjpjYSIsImp0aSI6Ijk2YjEzNmIwLWUifQ.ACbQdCPFZDKmFT4DkvJCGJBskWCoNGOcLlnHhBL3mBdUK5qexoDTp-cRcAj8jQS5zu4Hokr3V6T1LO5438kFQFPIjKo_iSDPOfy877WNfGt-_s4uNe6XZVLTHjScTA8ERJaQmpZ7yNVrf5L8m2TsBFgjRDoiCQKKmKkgSvb1w6-jCzQggnTScYk80Or-2G2lf0APsaAHP_iW6DBRnhdaCtXN9C1GcqCXVqXBWIu9NT59GLBo8H0WhGJWZtnIb0ACxgvEbQvR8yaQMzdRoWuRI1VQkeMowna4oPco6YUlAuTANTaL8TYerSZHLzNfsCB003lZnIkGvpTmo_-Ecfa8sQ&state=2dcf27ca-20e6-4e13-a77c-e5b3b86d3a87&nonce=43b2c0a6-de71-40ea-96dc-5b62e95790df&scope=openid%20payments&response_type=code%20id_token&redirect_uri=https%3A%2F%2Fconnect.truelayer.com%2Fredirect%2Fopenbanking"
},
"scenario": "OpenBankingToWallet",
"error_code": null,
"error_message": null,
"closing_balance": 56475,
"funding_source": {
"id": "32db45e9-959b-dcae-c7ed-d0c5770970da"
},
"payee": {
"id": "e07648f2-0900-4d7c-9f41-973b9daf3430"
},
"id": "6f85b636-1834-4f86-8371-d9a47260d99c",
"schedule": {
"id": null
},
"profile": {
"id": "d871c453-18fe-497e-a84a-01b0f14d7a7c"
}
}
}
]
}