# Recurring Agreement

## Introduction

If you need to set up regular recurring charges for consumers, you can easily achieve this through PayKKa's recurring payment feature. When making the first charge, specify to store the bank card information. Subsequent recurring charges can be completed using the recurring agreement and Token, making the process convenient and secure.

## Recurring Payment Process

### API Initiated Recurring Payment

Call the interface [Initiate Transaction](/payments/apis/payments/openapi/transaction/payments-opl_1)

Request Example


```json
{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "currency": "HKD",
  "amount": "800",
  "return_url": "https://url",
  "mit": false,
  "payment": {
    "payment_method": "BANKCARD",
    "store_payment_method": true,
    "token_usage": "SUBSCRIPTION",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c",
    "exp_year": "2029",
    "exp_month": "08",
    "cvv": "579",
    "holder_name": "Yi Westrich",
    "card_no": "5555555555554444"
  }
}
```

### Recurring Payment via Checkout

Create a checkout, and set the parameter to store the payment method (`store_payment_method=true`)

Request Example
[Create Session](/payments/apis/payments/openapi/session/session-opl_1)


```json
{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "trans_id": "m826xxx66465",
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "HOSTED",
  "currency": "HKD",
  "amount": "800",
  "return_url": "https://url",
  "payment": {
    "store_payment_method": true,
    "token_usage": "SUBSCRIPTION",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c"
  }
}
```

### Query Payment Result to Obtain Recurring Agreement

After a successful payment, you can obtain the recurring agreement id. The payment data is stored by PayKKa as a token (the `token` can be obtained via the transaction query interface)

[Query Payment](/payments/apis/payments/openapi/transaction/payments-query-opl_1)


```json
{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "error_code": "0000",
    "error_description": "request success",
    "merchant_id": "18356675194960",
    "trans_id": "m826xxx66465",
    "order_id": "GW206xxx28702",
    "status": "SUCCESS",
    "authorisation_type": "FINAL_AUTH",
    "capture_method": "AUTOMATIC",
    "amount": 8715,
    "currency": "EUR",
    "pay_finish_time": "2025-05-08T15:34:14+08:00",
    "token": "TK20535xxxx8947",
    "recurring_agreement_id": "RA4264524535435435",
    "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
    "expire_time": "2025-05-08T19:24:49+08:00",
    "payment": {
      "payment_method": "BANKCARD"
    },
    "card_info": {
      "bin": "400000",
      "last4": "3220",
      "card_brand": "VISA"
    },
    "balances": {
      "authed_amount": 8715,
      "captured_amount": 8715,
      "able_to_capture_amount": 0,
      "voided_amount": 0,
      "able_to_void_amount": 0,
      "refunded_amount": 0,
      "able_to_refund_amount": 8715
    }
  }
}
```

### Subsequent Recurring Payments

> You need to specify `mit=true`, indicating the transaction is initiated by the merchant


Request Example
[Initiate Transaction](/payments/apis/payments/openapi/transaction/payments-opl_1)


```json
{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "currency": "HKD",
  "amount": "800",
  "mit": true,
  "recurring_agreement_id": "RA4264524535435435",
  "payment": {
    "payment_method": "BANKCARD",
    "shopper_reference": "558b5cb1b8cbcc8496062155c69cf2ab",
    "token": "TK20231435132143229"
  }
}
```

## Recurring Agreement Management

### Cancel Recurring Agreement

To cancel a recurring agreement, use the [Delete Recurring Agreement](/payments/apis/payments/openapi/transaction/recurring-cancel-opl_1) interface, providing `recurring_agreement_id` and `shopper_reference`.

Cancelling a recurring agreement is irreversible. Please proceed with caution.