Octopus for Payment Setup API

Last updated: April 30, 2026

To accept Octopus payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to Octopus.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 1000,
3  "currency": "HKD",
4  "settings": {
5    "success_url": "https://example.com/payments/success",
6    "failure_url": "https://example.com/payments/failure"
7  }
8}

In the request body, provide the following:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Supported value: `HKD` Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`description` string	A description of the payment. Max length: 100
`reference` string	A reference you can use to identify the payment. Max length: 80


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "HKD",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "Octopus payment",
9  "payment_methods": {
10    "octopus": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "octopus"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

When all required fields are present, the payment_methods.octopus object shows a ready status.

Confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
octopus as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/octopus


1{
2  "id": "pay_dinkmi3v4vgutixpcw6mcdzt44",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_2g4ehcpm6phexgkzahlwxvbgne"
7  },
8  "processing": {
9    "landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=zjsdhd3",
10    "octopus_uri": "octopus://payment?token=zjsdhd3",
11    "token": "zjsdhd3"
12  },
13  "_links": {
14    "self": {
15      "href": "https://{prefix}.api.checkout.com/payments/pay_dinkmi3v4vgutixpcw6mcdzt44"
16    }
17  }
18}

The redirect step varies depending on where you're requesting the payment from.

To redirect a customer from a desktop browser:

Ensure that the Octopus App is installed on your customer's phone.
Redirect your customer to the processing.landing_url value from the response.
The URL displays a QR code.
Your customer must scan the code using their Octopus App and authorize the payment on their device.
After authorizing the payment, they're redirected to either your settings.success_url or settings.failure_url.

To redirect a customer from a mobile application:

Ensure that the Octopus App is installed on your customer's phone.
If the application is not installed, instruct your customers to install it.
Obtain the necessary token from the processing object in the response:
- For Android – Pass the processing.octopus_uri value to the Octopus App.
- For iOS – Use the processing.token value to construct a URL using a custom URL scheme to invoke the Octopus App.
The Octopus App launches on your customer's phone so they can authorize the payment.

Octopus for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer

Desktop

Mobile