This page describes how to create a payment session, which will allow you to send customer and order data to banked, display the checkout page, and check the status of the payment.
1. Authentication
Follow the instructions on the Authentication page to get your account credentials and generate an OAuth token. You'll need to use your test credentials until your application is ready to deploy.
You will use your API key and secret key with the /token endpoint to generate a scoped OAuth token. To use the example requests on this page, replace YOUR_TOKEN with the one you generate.
2. Create a Payment Session
Create a payment session to send customer and cart details to Banked. Send a POST request to the /payment_sessions endpoint to create a payment session.
By default you are only permitted to create payment sessions with payee details that match a previously linked account. In the test environment, you will have a fake bank account created automatically when you sign up. Unless you connect additional sandbox accounts, you must use the following payee details:
- account_number - 12345678
- sort_code - 010203.
The following cURL command creates a PaymentSession which contains a single item. Remember to Replace YOUR_TOKEN with the token you generated in the authentication step:
curl --location --request POST "https://api.banked.com/v2/payment_sessions" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data "{
\"reference\": \"Illuminate\",
\"success_url\": \"http://example.com/success?id=__PAYMENT_ID__\",
\"error_url\": \"http://example.com/error\",
\"line_items\": [
{
\"name\": \"Candles\",
\"amount\": 100,
\"currency\": \"GBP\",
\"quantity\": 4
}
],
\"payee\": {
\"name\": \"Gerald Wiley\",
\"account_number\": \"12345678\",
\"sort_code\": \"010203\"
},
\"email_receipt\": true
}"
Please note that reference is limited to 18 characters and can only contain letters, numbers, or spaces. Some banks are limited in the characters they accept, in which case Banked will strip or replace certain characters in the reference field to meet the bank's requirements.
If you know the user's name and email, add them in the payer object when creating the payment session. This allows your customer to skip the first screen of Banked's checkout and go straight to the bank selection screen, which creates a much smoother payment experience and improves checkout conversion!
The payment_sessions resource returns a PaymentSession object with the URL required to access the web checkout and complete the payment in the url field:
{
"amount": 400,
"created_at": "2019-11-01 15:48:26 UTC",
"currency": "GBP",
"end_to_end_id": "728d061b-8e47-4052-be4f-5f9bcdee39ff",
"error_url": "http://example.com/error",
"id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
"line_items": [
{
"amount": 100,
"currency": "GBP",
"description": null,
"name": "Candles",
"quantity": 4
}
],
"live": true,
"payee": {
"account_number": "12345678",
"name": "Gerald Wiley",
"sort_code": "010203"
},
"reference": "Illuminate",
"state": "awaiting_payer",
"success_url": "http://example.com/success?id=1ae1ce03-dfa9-4593-b487-65c656991cb5",
"url": "https://checkout.banked.com/1ae1ce03-dfa9-4593-b487-65c656991cb5",
"email_receipt": true
}
Use the placeholder __PAYMENT_ID__ anywhere in success_url and error_url if you need to use the newly-created payment ID when the user is redirected.
3. Checkout with the Mock Bank
Use the url value from the payment_sessions response to access the web checkout. You can see details of the PaymentSession and progress through the full checkout flow as a real customer would.
The key difference is we provide a 'mock' bank for testing, which doesn't require the need for a real UK bank account. It also offers the ability to test pending and failed PaymentSessions without any money moving between providers.
4. View Payment Status
Send a GET request to the /payment_sessions endpoint with the payment_id in the URL to retrieve the PaymentSession object. The response includes the status in the state field. See the Payment States reference page for details about the values in the state field.
If you have webhooks configured, you will receive a notification when the payment status changes.