Octopus for API only

Last updated: March 26, 2025

Octopus payment flow follows a two-step process:

post

https://api.checkout.com/payments


1{
2  "amount": 10,
3  "currency": "HKD",
4  "source": {
5    "type": "octopus"
6  },  
7  "success_url": "https://example.com/success",
8  "failure_url": "https://example.com/failure",
9  "reference": "ORD-5023-4E89"
10}

For the full API specification, see the API reference.

If you receive a 202 Accepted response code, your request was successful.


1{
2    "id": "pay_dinkmi3v4vgutixpcw6mcdzt44",
3    "status": "Pending",
4    "processed_on": "2024-06-18T13:20:51.2352985Z",
5    "processing": {
6        "landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=zjsdhd3",
7        "octopus_uri": "octopus://payment?token=zjsdhd3",
8        "token": "zjsdhd3"
9    },
10    "_links": {
11        "self": {
12            "href": "https://gwc.ckotech.co/payments/pay_dinkmi3v4vgutixpcw6mcdzt44"
13        }
14    }
15}

The redirection step varies depending on where you are requesting the payment:

A desktop browser
An application on a mobile phone

To request a payment from a desktop browser:

Ensure that the Octopus App is installed on your customer's phone.
Redirect your customer to the _links.self.href URL provided in the response.
The URL will display 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'll be redirected to either your success or failure URL.

To request a payment from an 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 is launched on your customer's phone, so they can authorize the payment there.

After you've requested the payment, you can use the id found in the payment response to retrieve details about the payment.

For more details, see Get payment details and our API reference.

Octopus supports both partial and full refunds.

The Octopus refund process varies depending on the payment method your customer selected. After Octopus approves a refund, if your customer paid using:

An e-wallet (usually Apple Pay or Google Pay) – The refund is automatically processed and the funds are transferred to the wallet.
An Octopus contactless card – The customer must collect the refund using their Octopus app or an Octopus card machine. If they do not collect the refund within 90 days after approval, the refund expires.

You can refund the payment in the Dashboard.

Alternatively, call the Refund a payment endpoint, and provide the payment_id value from the Request a payment response as the {id} path parameter.

post

https://api.checkout.com/payments/{id}/refunds


1{
2  "amount": 20
3}


1{
2  "action_id": "act_c4x2vjvnx4uelb4io72fa4e57a",
3  "_links": {
4    "payment": {
5      "href": "https://api.checkout.com/payments/pay_fzzdurog3squjj2ityho7x3o64"
6    }
7  }
8}

Octopus refunds can have the following statuses in the Dashboard:

Status Description

Status	Description
`Deferred Refund`	The refund request is created. This status indicates one of the following: The refund is in progress and awaiting Octopus to approve or decline it. Octopus approved the refund, but the customer has not yet collected it.
`Refunded`	The refund is approved. Depending on the payment method the customer used, this status indicates one of the following: For e-wallet payments – The refund was sent to the customer's e-wallet. For Octopus contactless card payments – The customer collected the refund.
`Captured`	The refund is declined. Depending on the payment method the customer used, this status indicates one of the following: For e-wallet payments – Octopus declined the refund and no funds were transferred to the customer's e-wallet. For Octopus contactless card payments – Octopus approved the refund, but the customer did not collect it within 90 days. In both cases, the original payment status remains as `Captured`. You can create another refund request if needed.

Deferred Refund

The refund request is created.

This status indicates one of the following:

The refund is in progress and awaiting Octopus to approve or decline it.
Octopus approved the refund, but the customer has not yet collected it.

Refunded

The refund is approved.

Depending on the payment method the customer used, this status indicates one of the following:

For e-wallet payments – The refund was sent to the customer's e-wallet.
For Octopus contactless card payments – The customer collected the refund.

Captured

The refund is declined.

Depending on the payment method the customer used, this status indicates one of the following:

For e-wallet payments – Octopus declined the refund and no funds were transferred to the customer's e-wallet.
For Octopus contactless card payments – Octopus approved the refund, but the customer did not collect it within 90 days.

In both cases, the original payment status remains as Captured. You can create another refund request if needed.

In your test environment:

Download the test version of the Octopus App for Android and iOS.
Contact Octopus to top-up your test wallet.
Perform a payment flow using the test Octopus App.

In your test environment:

Download the test version of the Octopus App for Android and iOS.
If needed, contact Octopus to top up your test wallet.
Perform a payment flow using the test Octopus App.
Call the Refund a payment endpoint, provide the payment_id value from the test payment, and set the refund amount to any of the following values, depending on the outcome you want to simulate:

Refund status	Description	Amount
`Refunded`	The refund is successful.	Any multiple of 100. For example: `100` `200` `300`
`Captured`	Octopus declined the refund.	Any amount ending in 10. For example: `10` `110` `210` `310`
	The refund expired after 90 days.	Any amount ending in 51. For example: `51` `151` `251` `351`
	The refund was declined and not collected.	Any amount ending in 52. For example: `52` `152` `252` `352`
	The refund exceeds the e-wallet's annual limit.	Any amount ending in 53. For example: `53` `153` `253` `353`

The following table lists the response codes you may receive when processing Octopus payments:

Response code	Description
`20001`	Refer to card issuer
`200P1`	Over daily limit
`20016`	Card not initialized
`20017`	Customer cancellation
`20019`	Declined Payment - Transaction has expired
`20061`	Activity amount limit exceeded
`20068`	Internal error

Octopus for API only

Request a payment

Request example

Response example

Redirect the customer

Desktop

Mobile

Get payment details

Refund a payment

Request example

Response example

Refund status in the Dashboard

Test your integration

Test refunds

Response codes