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.
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.
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 replaceAPPLICATION_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 replacePAYMENT_ID
in the API endpoint with the paymentid
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