Online Pet Shop: E-Commerce 1-Click Checkout
Scenario A: Online Pet Shop, Luna Store, is an Australian e-commerce retailer that wants to enable Pay by Bank as a one-click checkout payment method. They need to have payment mandates in place so that users can make one-click payments going forward. These mandates will have no end date and will be variable amounts, because the users’ cart size will be different for each purchase.
Step 1: The customer agrees to use Pay by Bank for 1-Click checkout at Online Pet Shop. The customer authorizes the mandate in their banking app.
Step 2: Online Pet Shop creates a Pay by Bank mandate.
POST /v2/mandatesjsoncurl --location --request POST "https://api.banked.com/v2/payment_sessions" \ --header "Content-Type: application/json" \ --user "YOUR_API_KEY:YOUR_API_SECRET" \ --data " { "currency": "AUD", "external_reference": "54a4fa72-d7b1-4328-b8c2-5a35c730cc2b", // set by merchant "description": "Enable 1-click checkout for Outback Pet Shop online purchases.", "destination": { "account_type": "banked_bank_account", "bank_account_id": "d8e74781-5fdb-40c8-9d08-54da83495efb" }, "payment_terms": { "terms_type": "variable", "frequency": "adhoc", "count": null, "max_amount": 100000, // (in cents) required in Australia }, "source": { "account_type": "plain_bank_account", "account_owner_name": "Gerald Wiley", "account_identifier": { "identifier_type": "BSBAccountNumber", "bsb": "111111", "account_number": "0312345678" "actions": [ { "action_type": "create_mandate_attempt" } } } }Sample 200 Response
json{ "id": "8086851c-14ac-4341-97dd-bfa17da0f045", "mode": "test", "state": "created", "created_at": "2023-08-01T12:32:00.000Z", "currency": "AUD", "external_reference": "54a4fa72-d7b1-4328-b8c2-5a35c730cc2b", "description": "Enable 1-click checkout for Outback Pet Shop online purchases.", "payment_terms": { "terms_type": "variable", "frequency": "adhoc", "max_amount": 100000, "count": null, }, "validity_start_date": "2024-08-01", // will default to current date "validity_end_date": null, // null when not specified in the request "latest_action": { "id": "bf409f6f-e060-454c-8c09-2f6adcb2554b", "mandate_id": "8086851c-14ac-4341-97dd-bfa17da0f045", "action_type": "create_mandate_attempt", "status": "in_progress", "created_at": "2023-08-01T12:30:00.000Z" }, "next_actions": { "completion_paths": [ { "action_type": "await" } ], "alternate_paths": [ { "action_type": "cancel_mandate" } ] } }Step 3: User is now able to complete 1-click payments per the active mandate.
Online Pet Shop will initiate 1-click payments using
POST /v2/payment_sessions.json{ "mandate":{ "token": "8086851c-14ac-4341-97dd-bfa17da0f045", }, "error_url": null, // not required for account not present transactions "success_url": "http://onlinepetshop.au/success", //required but not actioned upon "currency": "AUD", "reference": "pets0123456789", "description": "Online Pet Shop purchase.", "amount": 10000, //amount is in cents }Bonus Step 4: Online Pet Shop wants to retrieve the mandate details so that they can validate mandate status before making payments.
Online Pet Shop can retrieve details using
GET /v2/mandates/{mandate_id}for individual mandates orGET /v2/mandatesfor multiple mandates, up to a max of 100 items.Sample Response:
json{ "id": "788e6d08-bb99-43bc-91c5-825aaa5c71b9", "mode": "test", "state": "pending", "created_at": "2023-08-01T12:30:00.000Z", "currency": "AUD", "external_reference": "54a4fa72-d7b1-4328-b8c2-5a35c730cc2b", "description": "mandate for your shopping account", "payment_terms": { "terms_type": "variable", "frequency": "adhoc", "count": 10, "max_amount": 3000 }, "validity_start_date": "2023-01-01", "validity_end_date": "2023-12-31", "latest_action": { "id": "1ae1ce03-dfa9-4593-b487-65c656991cb5", "mandate_id": "788e6d08-bb99-43bc-91c5-825aaa5c71b9", "action_type": "create_mandate_attempt", "status": "in_progress", "created_at": "2023-08-01T12:30:00.000Z" }, "next_actions": { "completion_paths": [ { "action_type": "await" } ] } }Bonus Step 5: User would like to cancel the mandate.
If a user initiates a request with their bank to cancel their mandate in favor of no mandate or a new mandate or for any reason, Online Pet Shop will receive status webhooks and can make updates to specific mandates using
POST /v2/mandates/{mandate_id}/actions. See below for a sample cancellation:json{ "action_type": "cancel_current_mandate_attempt", "payload": { "reason": "cancellation_reason": "customer_requested" "narrative": // free text field to store a description to accompany the given reason code. } }
Banked Telecom: Monthly Subscription Billing
Scenario B: Banked Telecom is a regional telecommunications service provider that wants to offer Pay by Bank as a payment options for their customers who make fixed monthly payments to pay their internet bill. Their payment mandates will specify the amount that is authorized or payment have an end date depending on the nature of their service agreement with the customer.
Step 1: The customer agrees to use Pay by Bank to pay their monthly home internet plan. The customer authorizes the payment in their banking application.
Step 2: Banked Telecom creates a Pay by Bank mandate.
Start by initiating a call to
POST /v2/mandateswith the request body:json{ "currency": "AUD", "external_reference": "KangatelExtRef123456", // set by merchant "description": "Monthly billing - KangaTel Basic Plan", "destination": { "account_type": "banked_bank_account", "bank_account_id": "d8e74781-5fdb-40c8-9d08-54da83495efb" }, "payment_terms": { "terms_type": "fixed", "frequency": "monthly", "max_amount": 6000,// set relative to the price plan }, "validity_start_date": "2024-08-01", "validity_end_date": null, // set if the service contract has an expiration date "actions": [ { "action_type": "create_mandate_attempt", "payload": { "customer_ip_address": "127.0.0.1", "source": { "account_type": "plain_bank_account", "account_owner_name": "Gerald Wiley", "account_identifier": { "identifier_type": "BSBAccountNumber", "bsb": "111111", "account_number": "0312345678" } } } }, ] }Sample 200 Response
json{ "id": "8086851c-14ac-4341-97dd-bfa17da0f045", "mode": "test", "state": "created", "created_at": "2023-08-01T12:32:00.000Z", "currency": "AUD", "external_reference": "KangatelExtRef123456", "description": "Monthly billing - KangaTel Basic Plan", "token": "c147cce1-3099-436d-a163-14dece454797", "payment_terms": { "terms_type": "fixed", "frequency": "monthly", "amount": 6000, }, "validity_start_date": "2024-08-01", "validity_end_date": null, "latest_action": { "id": "bf409f6f-e060-454c-8c09-2f6adcb2554b", "mandate_id": "8086851c-14ac-4341-97dd-bfa17da0f045", "action_type": "create_mandate_attempt", "status": "in_progress", "created_at": "2023-08-01T12:30:00.000Z" }, "next_actions": { "completion_paths": [ { "action_type": "await" } ], "alternate_paths": [ { "action_type": "cancel_mandate" } ] } }Step 3: Each month on the billing date, Banked Telecom initiates a Pay by Bank transaction per the active mandate.
Banked Telecom will initiate monthly bill payments using
POST /v2/payment_sessions.json{ "error_url": null, // not required for account not present transactions "success_url": null, // not required for account not present transactions "reference": "KangaTelOrder123456", "external_reference": "external-reference", "amount": 6000, "payee": { "name": "KangaTel", "account_number": "12345678", "sort_code": "123456" }, "payer": { "name": "John Doe", "email": "john.doe@banked.com" }, "mandate": { "token": "c147cce1-3099-436d-a163-14dece454797" } }Step 4: The user upgrades their KangaTel plan, and Banked Telecom updates the payment mandate.
Banked Telecom will create an action against an active mandate to update the mandate using
POST /v2/mandates/{mandate_id}/actions.json{ "action_type": "amend_mandate", "payload": { "changes": { "payment_terms": { "max_amount": 10000 } } } }