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

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

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_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

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

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

url string

URL for the Checkout for this PaymentSession .

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_cents": 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 beensubmitted .

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.