Creating a batch payment session
This page will help take your first steps with creating a batch payment session
Banked's batch payments API is currently in private beta, if you would like to use it please contact us or talk to your Account Manager
You need to have linked a bank account via the Banked console before you can use the batch payment session endpoint. This is because some providers require payer details upfront before we can create an authorisation url to redirect to.
You can find more about connecting an account to the Banked Console here.
1. Create a Developer Account
Sign up for a developer account and get access to the Banked console. From here you can setup your business, and start taking payments.
2. Get test keys
After activating your account you are able to access your Server API test keys in the console by navigating to Test Application
-> Configuration
. You can use these to create payments in our sandbox environment where no money will be transferred to/from providers.
To use the examples below, replace YOUR_API_KEY
with your own.
3. Generate a Batch Payment Session
The following cURL command creates a BatchPaymentSession
which contains an array of payments. Remember to Replace YOUR_API_KEY
with your test key, and YOUR_API_SECRET
with your test secret.
curl --location --request POST "https://api.banked.com/v2/batch_payment_sessions" \
--header "Content-Type: application/json" \
--user "YOUR_API_KEY:YOUR_API_SECRET" \
--data "{
\"success_url\": \"https://example.com/success\",
\"error_url\": \"https://example.com/error\",
\"provider_id\": \"36293c8a-b118-472b-bc13-6aa53291134b\",
\"bank_account_id\": \"c3f87070-c2d8-4dbd-8943-7e280fc4c8fb\",
\"currency\": \"GBP\",
\"payees\": [
{
\"name\": \"Example Ltd.\",
\"account_identifier\": \"01020312345678\",
\"identifier_type\": \"SortCodeAccountNumber\",
\"amount\": 100,
\"reference\": \"ref12\",
\"client_id\": \"93249158-365D-449E-BE1B-F64971E89942\"
},
{
\"name\": \"Another Example Ltd.\",
\"account_number\": \"00000000\",
\"sort_code\": \"000000\",
\"amount\": 100,
\"reference\": \"ref13\",
\"client_id\": \"187F7A2A-18C3-4BA4-B094-35B4C0C11950\"
}
]
}"
Please note that for batch payments, payee reference
is limited to 13 characters, and can only contain letters, numbers and spaces. Banked appends 5 additional characters at the end of the reference. This is done to reconcile the payments in the future.
After running this in your terminal, you'll see the response will return a BatchPaymentSession
object with the URL required to authorise the payment.
{
"id":"1ae1ce03-dfa9-4593-b487-65c656991cb5",
"created_at":"2019-11-01 15:48:26 UTC",
"currency":"GBP",
"error_url":"http://example.com/error",
"provider_id":"cbf2e4fb-ca33-4276-b5dc-2b9ed00fd0aa",
"success_url":"http://example.com/success",
"live":true,
"payees":[
{
"end_to_end_id":"728d061b-8e47-4052-be4f-5f9bcdee39ff",
"account_identifier":"01020312345678",
"identifier_type": "SortCodeAccountNumber",
"name":"Example Ltd.",
"reference":"topup-201236DJIPOHCCs",
"amount":100,
"reference":"TCNzEn ref12",
"client_id": "93249158-365D-449E-BE1B-F64971E89942"
},
{
"end_to_end_id":"4d6ea50f-4a0a-4d35-a934-ccfe4f9c5e25",
"account_identifier":"01020312345678",
"identifier_type": "SortCodeAccountNumber",
"name":"Another Example Ltd.",
"reference":"topup-201236DJIPOHRRs",
"amount":100,
"reference":"fdF2ih ref13",
"client_id":"187F7A2A-18C3-4BA4-B094-35B4C0C11950"
}
],
"state":"awaiting_payment_consent",
"url":"https://bank.com/authorize"
}
4. Checkout with the Bank URL
Use the provided URL to access your bank's authorisation process. When this is complete Banked will redirect you the specified success or error URLs.
Individual payment verification
By creating a batch payment session with a linked account, after the batch payment has been authorised we will periodically check for the presence of the individual batch transactions in the account statement.
We will attempt to match transactions 4 times in the first 24 hours after a batch has been created, then once every 24 hours until 7 days after the batch was created. Any individual payments not 'reconciled' at this point, will be marked as failed. It is also possible to trigger a reconciliation check, either via the API using the refresh endpoint, or manually via the developer console.
You can choose to receive Webhooks about individual payment status updates in two ways;
- In aggregate - batch payment sent & failed Webhooks
- On a transaction by transaction basis - batch individual payment sent / batch individual payment failed
Updated 8 months ago