Payment Session Object

The PaymentSession is the core object containing all of the information related to a single payment.

VALUES

amount integer

Total amount for thisPaymentSession, in minor currency.

created_at timestamp

Date / time that this PaymentSession was created.

currency string

Currently we only support GBP.

end_to_end_id string

A unique identifier for this PaymentSession that is visible to all parties involved.

error_url string(optional)

URL to re-direct to after a failed payment viaCheckout.
If this value isn't provided, the user will not be redirected after landing on the Banked error page.

id string

Unique ID for this PaymentSession .

line_items array

An array of Line Item objects.

name
string

Name of item

description
string

Description of item (optional)

amount
integer

Total amount in 1/100's of currency

currency
string

ISO 4271 Currency Code - Currently we only support GBP

quantity
integer

Quantity of this item

live boolean

Indicates whether the PaymentSession was created using live or test authentication credentials.

payee object

A single Payee object with the details of who and where the Payment is to be made.

name
string

Name of payee (optional)

account_number
string

UK Bank account number (8 digits)

sort_code
string

UK Bank sort code (6 digits)

reference string

A custom reference included with the bank transaction (i.e. appears in the Provider's system)

18 Characters Maximum

state string

The current state of the PaymentSession .

The possible states are:
awaiting_payer,
awaiting_provider,
awaiting_payment_consent,
pending,
sent,
failed

success_url string(optional)

URL to re-direct to after a successful payment via Checkout.
If this value is not provided, the user will not be redirected after landing on the Banked success page.

url string

URL for the Checkout for this PaymentSession .

payerobject (optional)

A single Payer object with the details of who th will be made by.
If provided, the screen where the user enter's these details in the Banked checkout will not be displayed.

name
string

Name of payer

email
string

Email address of payer

EXAMPLE PAYMENT SESSION OBJECT

-x- CODE language-json -x- {
   "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": "123456"
   },
   "reference": "Illuminate",
   "state": "awaiting_payer",
   "success_url": "http://example.com/success",
   "url": "https://banked.me/pay/1ae1ce03-dfa9-4593-b487-65c656991cb5"
}

Create a Payment Session

In order to create a new PaymentSession you need to send a PaymentSession object to the following endpoint. Authorise the requests by including your API Key/Secret as shown.

post /api/v2/payment_sessions/

Request

Arguments

success_url string

URL to re-direct to after a successful payment via Checkout

error_url string

URL to re-direct to after a failed payment via Checkout

line_items array

An array of Line Item objects.

name
string

Name of item

description
string

Description of item (optional)

amount_cents
integer

Total amount in 1/100's of currency.

currency
string

ISO 4271 Currency Code - Currently we only support GBP

quantity
integer

Quantity of this item

payee object

A single Payee object with the details of who and where the is to be made to.

name
string

Name of payee (optional)

account_number
string

UK Bank account number (8 digits)

sort_code
string

UK Bank sort code (6 digits)

reference string

A custom reference included with the bank transaction (i.e. appears in the Provider's system)

18 Characters Maximum

EXAMPLE REQUEST

-x- CODE language-bash -x- curl --location --request POST "https://banked.me/api/v2/payment_sessions" \
 --header "Content-Type: application/json" \
 -u "YOUR_API_KEY:YOUR_API_SECRET" \
 --data "{
   \"reference\": \"Illuminate\",
   \"success_url\": \"http://example.com/success\",
   \"error_url\": \"http://example.com/error\",
   \"line_items\": [
     {
       \"name\": \"Candles\",
       \"amount_cents\": 100,
       \"currency\": \"GBP\",
       \"quantity\": 4
     }
   ],
   \"payee\": {
     \"name\": \"Gerald Wiley\",
     \"account_number\": \"12345678\",
     \"sort_code\": \"123456\"
 }
}"

Response

Returns aPaymentSession object if successful, or one of our standard error's if something went wrong.

Delete a Payment Session

Permanently deletes a PaymentSession. It cannot be undone. It immediately cancels the checkout link.

Can only be done if the Payment has not been submitted

DELETE /api/v2/payment_sessions/:id

Request

Arguments

payment_session string

The ID of thePaymentSession to be deleted.

EXAMPLE REQUEST

-x- CODE language-bash -x- curl -X DELETE \
 https://banked.me/api/v2/payment_sessions/bc7a09ce-6b18-4ea8-adc2-a44448f961b1 \
   -u "YOUR_API_KEY:YOUR_API_SECRET"

Response

If successful the request returns a 204.

Get a Payment Session

Retrieves a single PaymentSession.

GET /api/v2/payment_sessions/:id

Request

Arguments

payment_session string

The ID of thePaymentSession to be retrieved.

EXAMPLE REQUEST

-x- CODE language-bash -x- curl -X GET \
 https://banked.me/api/v2/payment_sessions/bc7a09ce-6b18-4ea8-adc2-a44448f961b1 \
   -u "YOUR_API_KEY:YOUR_API_SECRET"

Response

Returns a single PaymentSession object if successful, or one of our standard error codes if something went wrong.