📘

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