> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API integration

> A manual API integration roadmap for one-time payment and subscription payment.

API integration is suitable when you need full control over the payment flow. You call the Waffo REST API directly and connect payment, subscription, refund, and Webhook handling to your own system.

## Applicable scenarios

* Server-to-server payment processing
* You already have your own hosted checkout page or payment form
* Custom integration requiring maximum flexibility

## Integration roadmap

<Steps>
  <Step title="Choose the product">
    Choose one-time payment for single-charge orders, or subscription payment for recurring billing.
  </Step>

  <Step title="Integrate required APIs">
    One-time payment requires order create, order inquiry, and payment notification. Subscription requires subscription create, subscription inquiry, subscription status notification, and subscription payment notification.
  </Step>

  <Step title="Add conditional APIs as needed">
    Add cancel, refund, refund inquiry, refund notification, subscription manage, or subscription change only when your business flow needs them.
  </Step>

  <Step title="Use API Reference for field details">
    Request fields, response fields, enums, and signing rules are maintained in [API Reference](/api-reference/introduction). Do not copy field definitions from offline PDFs.
  </Step>

  <Step title="Test in sandbox">
    Use [Sandbox and testing](/en/developer-docs/getting-started/sandbox), including Apple Pay and Google Pay checks if needed.
  </Step>

  <Step title="Submit acceptance materials">
    Download the <a href="/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">one-time payment acceptance template</a> or <a href="/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">subscription acceptance template</a>, fill in the executed cases, and submit the result to the Waffo technical support group.
  </Step>
</Steps>

## Base URL

| Environment | URL                             |
| ----------- | ------------------------------- |
| Sandbox     | `https://api-sandbox.waffo.com` |
| Production  | `https://api.waffo.com`         |

## Request format

* Content-Type: `application/json` (UTF-8 encoding)
* All requests use HTTP POST
* Request headers must include `X-API-KEY` and `X-SIGNATURE`

## Response format

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
```

* `code` is `"0"` indicates success
* On failure, `code` is an error code (for example `"A0003"`), and `data` is empty
* Response header `X-SIGNATURE` contains the Waffo signature and **must be verified**

## Core APIs

### One-time payment

| API                                                  | Required    | Description                                                                       |
| ---------------------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `POST /api/v1/order/create`                          | Required    | Create a one-time payment order                                                   |
| `POST /api/v1/order/inquiry`                         | Required    | Query order status, including redirect loss, timeout, and Unknown Status recovery |
| Payment order notification                           | Required    | Receive terminal payment results and update the merchant order state              |
| `POST /api/v1/order/cancel`                          | Conditional | Cancel unpaid orders when your business supports cancellation                     |
| `POST /api/v1/order/refund`                          | Conditional | Initiate refunds when your business supports refunds                              |
| `POST /api/v1/refund/inquiry` or refund notification | Conditional | Query or receive refund processing results                                        |
| `POST /api/v1/order/capture`                         | Conditional | Required only for Auth-Capture manual capture mode                                |

### Subscription payment

| API                                     | Required    | Description                                                       |
| --------------------------------------- | ----------- | ----------------------------------------------------------------- |
| `POST /api/v1/subscription/create`      | Required    | Create a subscription                                             |
| `POST /api/v1/subscription/inquiry`     | Required    | Query subscription status and main payment information            |
| Subscription status notification        | Required    | Receive subscription activation, cancellation, and status changes |
| Subscription payment order notification | Required    | Receive first-payment and renewal payment results                 |
| `POST /api/v1/subscription/cancel`      | Conditional | Cancel subscriptions from the merchant side                       |
| `POST /api/v1/subscription/manage`      | Conditional | Generate a management URL for user-side subscription management   |
| `POST /api/v1/subscription/change`      | Conditional | Support plan upgrades or downgrades                               |
| `POST /api/v1/order/inquiry`            | Conditional | Query detailed failure reasons for subscription payment orders    |

### Configuration lookup

| API                                    | Required    | Description                                        |
| -------------------------------------- | ----------- | -------------------------------------------------- |
| `POST /api/v1/merchantconfig/inquiry`  | Recommended | Query merchant limits and configuration            |
| `POST /api/v1/paymethodconfig/inquiry` | Recommended | Query available payment methods and payment limits |

## Acceptance templates

After API integration and sandbox testing, download and fill in the matching template:

* <a href="/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">One-time payment acceptance template</a>
* <a href="/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">Subscription acceptance template</a>

Submit the completed acceptance result to the Waffo technical support group. See [Integration acceptance criteria](/en/developer-docs/tools-and-references/references/acceptance-criteria) before going live.