> ## 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.

# Overview

> 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](/docs/api-reference/introduction). Do not copy field definitions from offline PDFs.
  </Step>

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

  <Step title="Submit acceptance materials">
    For your first integration, download the <a href="/docs/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="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">subscription acceptance template</a>. Only for a subsequent one-time payment integration, download the <a href="/docs/files/developer-docs/acceptance/additional-integration-acceptance-cases.xlsx" download="additional-integration-acceptance-cases.xlsx">one-time payment additional integration 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`
* Raw HTTP requests must explicitly send `X-API-VERSION: 1.0.0`. SDKs manage this header automatically; do not set or override it. The `v1.3` value in API version history identifies documentation and external contract revisions and must not be used as this request header
* `subscriptionManagementUrl` is required for every `/api/v1/subscription/create` request

## 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, choose the template for your integration stage:

* First one-time payment integration: <a href="/docs/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>
* First subscription payment integration: <a href="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">Subscription acceptance template</a>
* Subsequent one-time payment integration: <a href="/docs/files/developer-docs/acceptance/additional-integration-acceptance-cases.xlsx" download="additional-integration-acceptance-cases.xlsx">One-time payment additional integration acceptance template</a>

<Info>
  This template applies to `ONE_TIME_PAYMENT`. Use it only after you have completed at least one integration acceptance and the current integration is not your first. Do not use it for your first integration.
</Info>

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