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 from the Github repository. 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.
Attention
You will need to replace base64(key:secret) in the Authorization header with your encoded credentials.
The cURL request below illustrates how to generate an oAuth token using the API:
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'
The response includes the token that you can use to create a business. The token 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.
To create a business, send a POST request to the /businesses endpoint as shown in the example below.
Attention
In the example below, replace YOUR_PARTNER_TOKEN in the Authorization header with the token from step 1.
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": "help@example.com"
},
"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": "help@example.com"
},
"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 the value of business_applications.id. This is the ID of the test application that was created for your business.
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, you are ready to initiate payment sessions. The first step is to create a scoped OAuth token for that application. The application token is different from the business token generated in step 1, as it is 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 data-urlencode parameter in the header, scope. Send the application ID you retrieved from the previous step in the scope field.
Attention
In the example request below, replace base64(key:secret) in the Authorization header with your encoded credentials. Also 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.
Attention
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": "jane@doe.com"
}
}'
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": "jane@doe.com"
},
"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, which would typically be done by the customer. For this example, copy and paste the url returned on the create payment session 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've completed your payment using Mock bank, you can check the status of the payment.
Attention
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": "jane@doe.com"
},
"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. Note that this is a test payment, so no real money is moved.
Congratulations, you have completed your first payment using Pay by Bank!