# Octopus for Unified Payments API
Octopus payment flow follows a two-step process:
1. [Request a payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).
## Request a payment
> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/payments`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments`
### Request example
```json
{
"amount": 1000,
"currency": "HKD",
"source": {
"type": "octopus"
},
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure",
"reference": "ORD-5023-4E89"
}
```
For the full API specification, see the [API reference](https://api-reference.checkout.com/#tag/Payments).
For Octopus, payment and refund amounts must end in a `0`.
### Response example
If you receive a `202 Accepted` response code, your request was successful.
```json
{
"id": "pay_dinkmi3v4vgutixpcw6mcdzt44",
"status": "Pending",
"processed_on": "2024-06-18T13:20:51.2352985Z",
"processing": {
"landing_url": "https://web-test.online.octopus.com.hk/oos/payment/?token=zjsdhd3",
"octopus_uri": "octopus://payment?token=zjsdhd3",
"token": "zjsdhd3"
},
"_links": {
"self": {
"href": "https://gwc.ckotech.co/payments/pay_dinkmi3v4vgutixpcw6mcdzt44"
}
}
}
```
## Redirect the customer
The redirection step varies depending on where you are requesting the payment:
- A desktop browser
- An application on a mobile phone
### Desktop
To request a payment from a desktop browser:
1. Ensure that the Octopus App is installed on your customer's phone.
2. Redirect your customer to the `_links.self.href` URL provided in the response.
The URL will display a QR code.
3. Your customer must scan the code using their Octopus App and authorize the payment on their device.
4. After authorizing the payment, they'll be redirected to either your success or failure URL.
### Mobile
To request a payment from an application:
1. Ensure that the Octopus App is installed on your customer's phone.
If the application is not installed, instruct your customers to install it.
2. 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
3. The Octopus App is launched on your customer's phone, so they can authorize the payment there.
---
## Get payment details
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](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) and our [API reference](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList).
---
## Refund a payment
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:
- Octopus Wallet – 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](https://dashboard.checkout.com).
Alternatively, call the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint, and provide the `payment_id` value from the [Request a payment](#Request_a_payment) response as the `{id}` path parameter.
> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/payments/{id}/refunds`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`
### Request example
```json
{
"amount": 2000
}
```
For Octopus, refund amounts must end in a `0`.
### Response example
```json
{
"action_id": "act_c4x2vjvnx4uelb4io72fa4e57a",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_fzzdurog3squjj2ityho7x3o64"
}
}
}
```
### Refund status in the Dashboard
Octopus refunds can have the following statuses in the Dashboard:
| 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 Octopus 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. |
---
## Test your integration
In your sandbox environment:
1. Download the test version of the Octopus App for [Android](https://apptest.oepay.octopus-cards.com/zinc/f09jfv-dfvdfv3-r4334-f3f34-ggrt-gtrg/external_testing_party.protected.apk) and [iOS](https://testflight.apple.com/join/6OXcMv7D).
2. Contact Octopus to add funds to your test wallet.
3. Perform a payment flow using the test Octopus App.
### Test refunds
In your sandbox environment:
1. Download the test version of the Octopus App for [Android](https://apptest.oepay.octopus-cards.com/zinc/f09jfv-dfvdfv3-r4334-f3f34-ggrt-gtrg/external_testing_party.protected.apk) and [iOS](https://testflight.apple.com/join/6OXcMv7D).
2. If needed, contact Octopus to add funds to your test wallet.
3. Perform a payment flow using the test Octopus App.
4. Call the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) 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` |
| `Captured` | The refund expired after 90 days. | Any amount ending in 51. For example:
- `51`
- `151`
- `251`
- `351` |
| `Captured` | The refund was declined and not collected. | Any amount ending in 52. For example:
- `52`
- `152`
- `252`
- `352` |
| `Captured` | The refund exceeds the e-wallet's annual limit. | Any amount ending in 53. For example:
- `53`
- `153`
- `253`
- `353` |
---
## Response codes
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 |