GuidesAPI Reference
Banked.com

Banked Partner Getting Started Guide

This page will help you quickly walk through a Partner flow - from setting up a business to creating and completing your first payment.

Suggest Edits

This step-by-step guide is designed to help you complete your first test payment using Banked. The best way to do this is to run these commands in Postman using the linked collection. If you have any questions during the process, reach out to Banked!

0. Set up your Postman

Download the associated Postman collection - the API calls there are numbered to correspond to the steps in this guide.

Run in Postman

📘

Collection Authorization settings

The Postman collection explicitly adds Authorization headers to every request.

1. Generate a Partner OAuth token

The first step in using the Banked APIs is to generate your OAuth token. You can read about the way Authentication works here.

Remember to base64-encode the key and secret you have been provided by the Banked team - you can do that using https://www.base64encode.org.

🚧

NB

You will need to replace base64(key:secret) in the Authorization header with your encoded credentials.

curl --location --request POST 'https://api.banked.com/oauth/token' \
--header 'Authorization: Basic base64(key:secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

In the response you will receive will contain the token you can use to create a business - this will be valid for 2 hours, after which you will need to generate a new one.

{
    "access_token": "exjNj8bkSWBpA129p9uryxcNRr8niNPy1crVyd7QNfM",
    "token_type": "Bearer",
    "expires_in": 7200,
    "created_at": 1643817378
}

You will need the access_token from the response for the next step.

2. Create a Business

Once you have your Partner OAuth token, you are able to create a business. You can find more information about creating a business here. An example request will look like this:

🚧

NB

You will need to replace YOUR_PARTNER_TOKEN with the token from step 1 in the Authorization header.

curl --location --request POST 'https://api.banked.com/partner/v1/businesses' \
--header 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Example Business",
    "registration_body": "UK Companies House",
    "registration_number": "123456789",
    "vat_number": "123456",
    "registered_address": {
        "line_1": "1 Street",
        "city": "City",
        "region": "State",
        "country": "GBR",
        "postal_code": "AB1 2CD"
    },
    "legal_type": "Limited Company",
    "website_url": "www.example.com",
    "settings": {
        "bank_accounts": [
            {
                "account_identifier": "01000112345678",
                "identifier_type": "SortCodeAccountNumber",
                "currency": "GBP"
            }
        ],
        "support_details": {
            "support_email": "[email protected]"
        },
        "logo_url": "http://example.com/png",
        "capabilities": {
            "avios": false,
            "unverified_payable": false,
            "external_refunds" :false
        }
    }
}'

The response will return information about your newly created Business:

{
    "bank_accounts": [
        {
            "account_identifier": "01000112345678",
            "currency": "GBP",
            "id": "f9f36cd0-2d5e-415a-9df6-4a580bff089e",
            "identifier_type": "SortCodeAccountNumber",
            "live": false,
            "name": null,
            "secondary_identifier": null
        },
        {
            "account_identifier": "01020312345678",
            "currency": "GBP",
            "id": "6fbebef9-f5a0-4255-8a40-565de25551cd",
            "identifier_type": "SortCodeAccountNumber",
            "live": false,
            "name": "Current Account",
            "secondary_identifier": null
        }
    ],
    "business_applications": [
        {
            "id": "feb68ff6-3c5f-4412-a4f0-28f52ce1c953",
            "mode": "test",
            "name": "Test Application"
        }
    ],
    "capabilities": {
        "avios": false,
        "unverified_payable": false,
        "external_refunds": false
    },
    "id": "37b4e0d9-19f6-4add-a2b6-6f7433a02f84",
    "legal_type": "Limited Company",
    "name": "Example Business",
    "registered_address": {
        "city": "City",
        "country": "GBR",
        "line_1": "1 Street",
        "line_2": null,
        "postal_code": "AB1 2CD",
        "region": "State"
    },
    "registration_body": "UK Companies House",
    "registration_number": "123456789",
    "support_details": {
        "support_email": "[email protected]"
    },
    "trading_address": {
        "city": "City",
        "country": "GBR",
        "line_1": "1 Street",
        "line_2": null,
        "postal_code": "AB1 2CD",
        "region": "State"
    },
    "vat_number": "123456",
    "website_url": "www.example.com"
}

You've now created your first Business!

Note down the value of business_applications.id - this is a test Application that was created for your business.
Also, note that by default a test bank account was created with an identifier 01020312345678 (this stands for sort code 010203 and account number 12345678) - you will use this later to create a test payment.

3. Generate an Application OAuth token

Now that you have a Business created, you are ready to initiate payment sessions. The first step is to create an OAuth token for that application - this is different from the one generated in step 1, as it's application-specific, and can only be used with the Payments API.

This will be almost the same API call as you performed in Step 1, but with an additional body parameter scope, where you will need to input the application ID you retrieved from the previous step.

🚧

NB

You will need to replace base65(key:secret) in the Authorization header with your encoded credentials.
You will need to replace APPLICATION_ID in the request body with the application ID you got from step 2.

curl --location --request POST 'https://api.banked.com/oauth/token' \
--header 'Authorization: Basic base64(key:secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'\
--data-urlencode 'scope=APPLICATION_ID'

The response will contain a token that's valid for 2 hours - you can check that your application scope is returned on the response.

{
    "access_token": "3hw0wicGm7VwbVyBmey58tMP2pSFBI8E4G54hpliJR4",
    "token_type": "Bearer",
    "expires_in": 7200,
    "scope": "feb68ff6-3c5f-4412-a4f0-28f52ce1c953",
    "created_at": 1643818825
}

4. Generate a Payment Session

You are ready to create a payment session on behalf of the business you just created - this will let you specify the payment amount, the destination account, as well as the payer details (which are optional). You can read more about creating a payment session here.

A payment session will generate a unique URL that can be used to complete a payment.

🚧

NB

You will need to replace YOUR_APPLICATION_TOKEN with the token from step 3 in the Authorization header.

The following command will create a test payment to be payable to the bank account that was created for your business in step 2. 

curl --location --request POST 'https://api.banked.com/v2/payment_sessions' \
--header 'Authorization: Bearer YOUR_APPLICATION_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "error_url": "https://example.com",
    "success_url": "https://example.com",
    "line_items": [
        {
            "name": "Accounting services",
            "amount": 10000,
            "quantity": 1,
            "currency": "GBP"
        }
    ],
    "reference": "jhfjhfkjhf",
    "payee": {
        "name": "Current Account",
        "account_number": "12345678",
        "sort_code": "010203"
    },
    "payer": {
        "name": "Jane Doe",
        "email": "[email protected]"
    }
}'

The response will return details about your payment session.

{
    "amount": 10000,
    "amount_formatted": "£100.00",
    "business_application_id": "feb68ff6-3c5f-4412-a4f0-28f52ce1c953",
    "created_at": "2022-02-03T10:37:46.672Z",
    "currency": "GBP",
    "email_receipt": false,
    "end_to_end_id": null,
    "error_url": "https://example.com",
    "id": "04c54ba2-d5be-4ff5-9a12-aed009b28fd8",
    "line_items": [
        {
            "amount": 10000,
            "amount_cents": 10000,
            "amount_formatted": "£100.00",
            "currency": "GBP",
            "description": null,
            "name": "Accounting services",
            "quantity": 1
        }
    ],
    "live": false,
    "payee": {
        "bank_account_id": "6fbebef9-f5a0-4255-8a40-565de25551cd",
        "name": "Current Account",
        "account_identifier": "01020312345678",
        "identifier_type": "SortCodeAccountNumber",
        "sort_code": "010203",
        "account_number": "12345678"
    },
    "payer": {
        "name": "Jane Doe",
        "email": "[email protected]"
    },
    "reference": "jhfjhfkjhf",
    "sent_at": null,
    "state": "awaiting_provider",
    "success_url": "https://example.com",
    "url": "https://checkout.banked.com/04c54ba2-d5be-4ff5-9a12-aed009b28fd8"
}

Keep note of the payment session ID (id) - you will need this in the next step to check the status of your payment.

You can now complete the payment session - this is what the end customer will do. For this copy and paste the url returned on the payment session creation response into your browser, choose "Mock Bank" as a payment option, and follow the authorisation steps.

5. Check the status of your payment

Once you're completed your payment using Mock bank, you can check the status of the payment.

🚧

NB

You will need to replace YOUR_APPLICATION_TOKEN with the token from step 3 in the Authorization header.
You will need to replace PAYMENT_ID in the API endpoint with the payment id you got from step 4.

curl --location --request GET 'https://api.banked.com/v2/payment_sessions/PAYMENT_ID' \
--header 'Authorization: Bearer YOUR_APPLICATION_TOKEN'

The response will return the details of the payment, including the payment state:

{
    "amount": 10000,
    "amount_formatted": "£100.00",
    "business_application_id": "feb68ff6-3c5f-4412-a4f0-28f52ce1c953",
    "created_at": "2022-02-03T10:37:46.672Z",
    "currency": "GBP",
    "email_receipt": false,
    "end_to_end_id": "BNKD-yZUfDRQ0WVmQwfqi",
    "error_url": "https://example.com",
    "id": "04c54ba2-d5be-4ff5-9a12-aed009b28fd8",
    "line_items": [
        {
            "amount": 10000,
            "amount_cents": 10000,
            "amount_formatted": "£100.00",
            "currency": "GBP",
            "description": null,
            "name": "Accounting services",
            "quantity": 1
        }
    ],
    "live": false,
    "payee": {
        "bank_account_id": "6fbebef9-f5a0-4255-8a40-565de25551cd",
        "name": "Current Account",
        "account_identifier": "01020312345678",
        "identifier_type": "SortCodeAccountNumber",
        "sort_code": "010203",
        "account_number": "12345678"
    },
    "payer": {
        "name": "Jane Doe",
        "email": "[email protected]"
    },
    "reference": "jhfjhfkjhf",
    "sent_at": "2022-02-03T11:28:36.701Z",
    "state": "sent",
    "success_url": "https://example.com",
    "url": "https://checkout.banked.com/04c54ba2-d5be-4ff5-9a12-aed009b28fd8"
}

If you have completed the payment in step 4, state will be set to sent, which means the payment has been sent (Although this is a test payment, where no real money moves).

Congratulations, you have completed your first payment using Pay by Bank!

Updated 28 days ago