> For the complete documentation index, see [llms.txt](https://docs.tupayonline.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tupayonline.com/english/api-documentation/deposit/subscriptions-process.md).

# Subscriptions Process

Lets you register a user's payment method (subscription creation) **without charging them**, and then charge them with regular deposits whenever you need. It also lets you query and cancel the subscription, and refund a charge to the user's Yape account.

**Available today:** Yape (Peru), with the payment methods `YPOC` (on-demand charges) and `YPOR` (recurring charges).

**Integration:** this guide is written from the point of view of a standard merchant integration with API v3, the same as the deposits one. The same credentials, the same HMAC signature authentication (`X-Login`, `X-Date` and `Authorization`), IP validation and the same environments are used. There is nothing additional or different to integrate beyond what is already used to operate with the API.

### 1. Environments

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Production  | `https://api.directa24.com`     |
| Staging     | `https://api-stg.directa24.com` |

The same credentials (`X-Login` and secret key) used for `/v3/deposits` apply.

### 2. How it works

1. **Creation:** you create the subscription with `POST /v3/payment_subscriptions`. It is left in `PENDING`.
2. **User confirmation:** the user approves it in the Yape app.
   * If you sent the user's phone number (`payer.phone`), Yape sends a push notification to their phone.
   * If you did not send it, the response includes a `confirmation_url`: show it to the user or redirect them so they open Yape and confirm.
3. **Query:** with `GET /v3/payment_subscriptions/{subscription_id}` you find out whether the user has already confirmed (`CONFIRMED`).

{% hint style="warning" %}
**We do not send a notification** when the user confirms: you must query.
{% endhint %}

4. **Charge:** with the subscription `CONFIRMED`, you charge with a regular deposit (`POST /v3/deposits`) using the same `payment_method` and the same `payer.id` as in the creation. The charge is processed without the user having to do anything.
5. **Cancellation:** with `DELETE /v3/payment_subscriptions/{subscription_id}`. After cancellation, deposits for that payment method are rejected until you create a new subscription.
6. **Refund:** if you need to return an already completed charge (for example, a cancelled service), request it with `POST /v3/refunds`. The money goes back to the user's Yape account, with no bank account required. See section 8.

#### Subscription types

| `payment_method` | Type                    | Use                                                                                                                                                        |
| ---------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `YPOC`           | On demand (`ON_DEMAND`) | Charges whenever you need them, for the amount of each deposit.                                                                                            |
| `YPOR`           | Recurring (`RECURRENT`) | The user authorizes an `amount` every `periodicity_months` months. **You initiate each charge** with a `YPOR` deposit; Yape does not charge automatically. |

A user can have both a `YPOC` and a `YPOR` subscription with you at the same time.

### 3. Authentication

It is the same as in the rest of API v3:

* `X-Login`: your login.
* `X-Date`: UTC date in the format `yyyy-MM-dd'T'HH:mm:ss'Z'`. It is valid for 15 seconds.
* `Authorization: D24 <signature>`: hexadecimal HMAC-SHA256 of `X-Date + X-Login + body` with your secret key. In `GET` and `DELETE` the body is empty.
* `Content-Type: application/json` on the `POST`.

### 4. Creation: `POST /v3/payment_subscriptions`

| Field                                                | Required    | Description                                                                                                                                                                                                                       |
| ---------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`                                            | Yes         | `PE`                                                                                                                                                                                                                              |
| `payment_method`                                     | Yes         | `YPOC` or `YPOR` (case-insensitive).                                                                                                                                                                                              |
| `payer.id`                                           | Yes         | The user's id on your platform (alphanumeric, up to 128 characters). **Send the same `payer.id` in the creation and in every charge**: that is how we find their subscription. It must be unique per user and must not be reused. |
| `payer.phone`                                        | No          | The user's Yape phone number, with or without `+51`. With phone: push to the phone. Without phone: a `confirmation_url` is returned.                                                                                              |
| `payer.first_name`, `payer.last_name`, `payer.email` | No          | Optional.                                                                                                                                                                                                                         |
| `amount`                                             | `YPOR` only | Amount in PEN that the user authorizes (0.01 to 2000.00).                                                                                                                                                                         |
| `periodicity_months`                                 | `YPOR` only | Months between charges (1 to 12).                                                                                                                                                                                                 |

{% tabs %}
{% tab title="YPOC with phone" %}
**Example: YPOC with phone (push)**

`POST /v3/payment_subscriptions`

```json
{
  "country": "PE",
  "payment_method": "YPOC",
  "payer": {
    "id": "user_123",
    "first_name": "Juan",
    "last_name": "Perez",
    "email": "juan@example.com",
    "phone": "934004110"
  }
}
```

{% endtab %}

{% tab title="YPOC without phone" %}
**Example: YPOC without phone (confirmation\_url)**

```json
{
  "country": "PE",
  "payment_method": "YPOC",
  "payer": { "id": "user_123" }
}
```

{% endtab %}

{% tab title="YPOR" %}
**Example: YPOR (10.00 PEN monthly)**

```json
{
  "country": "PE",
  "payment_method": "YPOR",
  "payer": { "id": "user_123", "phone": "934004110" },
  "amount": 10.00,
  "periodicity_months": 1
}
```

{% endtab %}
{% endtabs %}

#### Response

* **201 Created** (with `Location` header): new subscription in `PENDING`.
* **200 OK** with `"already_exists": true`: the user already had a subscription for that payment method (confirmed or pending). That same one is returned; no other is created.

`HTTP 201`

```json
{
  "subscription_id": "5151d093-a261-4a81-934a-4815a220f758",
  "payment_method": "YPOC",
  "status": "PENDING",
  "type": "ON_DEMAND",
  "source": "WEB",
  "expires_in": 1800,
  "expiration_date": "2026-10-20T20:57:41",
  "already_exists": false,
  "created_at": "2026-10-20T20:27:41"
}
```

Without a phone, the response also includes `"source": "MOBILE"` and `"confirmation_url": "..."`. The user has `expires_in` seconds to confirm; if they do not, the request expires and a new subscription must be created.

A creation without `payer.id` responds with HTTP 400 (see section 10).

### 5. Query: `GET /v3/payment_subscriptions/{subscription_id}`

`HTTP 200`

```json
{
  "subscription_id": "5151d093-a261-4a81-934a-4815a220f758",
  "payment_method": "YPOC",
  "status": "CONFIRMED",
  "type": "ON_DEMAND",
  "source": "WEB",
  "created_at": "2026-10-20T20:27:41",
  "activated_at": "2026-10-20T20:28:48"
}
```

If the subscription ended in `FAILED` or `CANCELLED`, the response includes the reason in `reason_code` and `reason_description` (see section 9):

`HTTP 200`

```json
{
  "subscription_id": "8c2f4e1a-5b7d-4c3e-9a61-2f0d7b6e4a19",
  "payment_method": "YPOC",
  "status": "FAILED",
  "type": "ON_DEMAND",
  "source": "WEB",
  "created_at": "2026-10-20T20:27:41",
  "reason_code": "ACCOUNT_INACTIVE",
  "reason_description": "The payer's account does not exist or is inactive"
}
```

**Recommendation:** while it is in `PENDING`, query every few seconds during the confirmation window (`expires_in`).

### 6. Cancellation: `DELETE /v3/payment_subscriptions/{subscription_id}`

* Only a `CONFIRMED` subscription can be cancelled.
* If it was already cancelled, it still responds 200.

`HTTP 200`

```json
{
  "subscription_id": "5151d093-a261-4a81-934a-4815a220f758",
  "payment_method": "YPOC",
  "status": "CANCELLED",
  "type": "ON_DEMAND",
  "source": "WEB",
  "created_at": "2026-10-20T20:27:41",
  "activated_at": "2026-10-20T20:28:48",
  "cancelled_at": "2026-10-20T20:31:07",
  "reason_code": "CANCELLED_BY_MERCHANT",
  "reason_description": "The subscription was cancelled by the merchant",
  "cancelled_by": "MERCHANT"
}
```

### 7. Charge: `POST /v3/deposits`

It is a regular deposit, with no changes to the contract. Use the same `payment_method` as the subscription and **the same `payer.id` as in the creation**. There is no need to send the document or any other payer data.

`POST /v3/deposits`

```json
{
  "invoice_id": "order-123",
  "amount": "25.50",
  "country": "PE",
  "currency": "PEN",
  "payment_method": "YPOC",
  "payer": { "id": "user_123" }
}
```

{% hint style="info" %}
**Important:**

* If the `payer.id` is different from the one in the creation, or you do not send it, we cannot find the subscription: the charge is rejected with `916` and nothing is charged.
* Do not send `payer.document` in `YPOC` / `YPOR` charges. If you do, the charge may stop finding the subscription (`916`), and so may that user's later charges.
  {% endhint %}

The result of the charge arrives like that of any deposit (notification to the `notification_url` and deposit query). Range per charge: 0.01 to 2000.00 PEN, also subject to the general deposit minimum.

**Recommendation:** since you decide when to charge, charge once the service has been provided and for the final amount. This avoids refunds due to cancellations.

### 8. Refund: `POST /v3/refunds`

Returns a completed `YPOC` or `YPOR` charge **to the user's Yape account**. It is the same refunds endpoint of API v3 used for any deposit; for Yape there is no need to send a bank account.

#### Rules

* Only `YPOC` / `YPOR` deposits in `COMPLETED` status.
* **Only for the full amount of the deposit.** There are no partial refunds, and each deposit allows a single refund.
* Up to **365 days** from the charge.
* Do not send `bank_account`; if it is sent, it is ignored.
* Your account must have refunds enabled and sufficient balance. The amount is deducted from your balance when the refund reaches `COMPLETED`.

#### Request

| Field                      | Required         | Description                                                                                                                                                 |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deposit_id`               | Yes              | Id of the deposit to refund (the one returned by `POST /v3/deposits`).                                                                                      |
| `invoice_id`               | Yes              | The `invoice_id` you sent in that deposit.                                                                                                                  |
| `amount`                   | No               | If you send it, it must equal the full amount of the deposit. If not, the full amount is refunded.                                                          |
| `notification_url`         | No               | URL where we notify you of status changes of this refund. If you do not send it, we use the "Refund URL" configured in your panel (Settings > Integration). |
| `X-Idempotency-Key` header | No (recommended) | Prevents creating two refunds if you retry the same request.                                                                                                |

`POST /v3/refunds`

```json
{
  "deposit_id": 301763579,
  "invoice_id": "order-123"
}
```

`HTTP 201`

```json
{
  "refund_id": 1006769
}
```

#### It is asynchronous

The response only confirms that the refund was registered. The result arrives later, usually within minutes:

| Status      | Meaning                                        |
| ----------- | ---------------------------------------------- |
| `PENDING`   | Registered, not yet sent to Yape.              |
| `DELIVERED` | Sent to Yape, waiting for the result.          |
| `COMPLETED` | Yape returned the money to the user's account. |
| `REJECTED`  | Yape rejected it.                              |

Each status change is notified with a `POST` to your `notification_url` (or your "Refund URL") with the body `{"refund_id": 1006769}`. This is different from the payment notification, which arrives at the "Confirmation URL" with `{"deposit_id": ...}`.

With the `refund_id`, query the status: `GET /v3/refunds/1006769`

`HTTP 200`

```json
{
  "deposit_id": 301763579,
  "merchant_invoice_id": "order-123",
  "status": "COMPLETED",
  "amount": 10.00
}
```

#### Refund errors

| Code | Type                           | HTTP | What it means / what to do                                                          |
| ---- | ------------------------------ | ---- | ----------------------------------------------------------------------------------- |
| 104  | `IDEMPOTENCY_KEY_ALREADY_USED` | 400  | You already used that `X-Idempotency-Key` for this deposit.                         |
| 208  | `RESOURCE_NOT_FOUND`           | 404  | The `deposit_id` does not exist, is not yours, or does not match the `invoice_id`.  |
| 705  | `REFUND_NOT_FOUND`             | 404  | On query: the `refund_id` does not exist or is not yours.                           |
| 800  | `REFUND_NOT_ENABLED`           | 400  | Your account does not have refunds enabled. Contact your account manager.           |
| 801  | `DEPOSIT_NOT_COMPLETED`        | 400  | The deposit is not yet `COMPLETED`.                                                 |
| 802  | `INVALID_AMOUNT_TO_REFUND`     | 400  | Amount different from the full deposit amount, or the deposit already has a refund. |
| 803  | `INSUFFICIENT_FUNDS`           | 400  | You do not have enough balance for the refund.                                      |
| 807  | `REFUND_IN_PROGRESS`           | 409  | Another refund of that deposit is being created. Retry in a few seconds.            |
| 808  | `REFUND_PERIOD_EXPIRED`        | 400  | More than 365 days have passed since the charge.                                    |

### 9. Subscription statuses

| Status      | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `PENDING`   | Waiting for the user to confirm in the app.                                                |
| `CONFIRMED` | Active: you can now charge.                                                                |
| `FAILED`    | The user rejected it, it expired, or Yape rejected it. A new subscription must be created. |
| `CANCELLED` | Cancelled (by you or by the user from the Yape app).                                       |

#### Reason (`reason_code`)

Sent only in `FAILED` and `CANCELLED`. It is our own code, the same for any provider; `reason_description` carries the text in English. In `CANCELLED`, `cancelled_by` is also sent: `USER` (the user cancelled it from the app) or `MERCHANT` (you cancelled it with `DELETE`).

| Status      | `reason_code`           | What happened / what to do                                               |
| ----------- | ----------------------- | ------------------------------------------------------------------------ |
| `FAILED`    | `USER_REJECTED`         | The user rejected the request in the app.                                |
| `FAILED`    | `ACCOUNT_INACTIVE`      | The user's account does not exist or is inactive.                        |
| `FAILED`    | `ACCOUNT_NOT_SUPPORTED` | The user's account type does not support subscriptions.                  |
| `FAILED`    | `ACCOUNT_BLOCKED`       | The user's account is blocked for online payments.                       |
| `FAILED`    | `CARD_INVALID`          | The associated card is invalid, blocked or expired.                      |
| `FAILED`    | `AUTHENTICATION_FAILED` | The user did not pass authentication.                                    |
| `FAILED`    | `AMOUNT_LIMIT_EXCEEDED` | The amount exceeds the user's limit.                                     |
| `FAILED`    | `EXPIRED`               | The user did not confirm in time.                                        |
| `FAILED`    | `PROVIDER_ERROR`        | The provider could not process the request. The creation can be retried. |
| `CANCELLED` | `CANCELLED_BY_MERCHANT` | You cancelled it with `DELETE` (`cancelled_by: MERCHANT`).               |
| `CANCELLED` | `CANCELLED_BY_USER`     | The user cancelled it from the app (`cancelled_by: USER`).               |

In any `FAILED` case a new subscription must be created in order to charge again. New values may appear: treat an unknown `reason_code` as generic.

### 10. Subscription errors

Format: `{"code": 916, "description": "...", "type": "PAYMENT_SUBSCRIPTION_REQUIRED"}`. Refund errors are in section 8.

| Code | Type                                        | HTTP | What it means / what to do                                                                                                                                                               |
| ---- | ------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 910  | `PAYMENT_SUBSCRIPTION_NOT_FOUND`            | 404  | The subscription does not exist or is not yours. Check the `subscription_id`.                                                                                                            |
| 911  | `PAYMENT_SUBSCRIPTION_NOT_CANCELLABLE`      | 409  | Only a `CONFIRMED` subscription can be cancelled.                                                                                                                                        |
| 912  | `PAYMENT_SUBSCRIPTION_PENDING_CONFIRMATION` | 409  | The user has not confirmed yet. In a deposit: wait for them to confirm. In a creation: there is a pending request; retry in a few minutes.                                               |
| 913  | `PAYMENT_SUBSCRIPTION_INVALID_REQUEST`      | 400  | Invalid request (unsupported payment method, or `amount` / `periodicity_months` missing in `YPOR`). Fix the request.                                                                     |
| 914  | `PAYMENT_SUBSCRIPTION_PROVIDER_REJECTED`    | 502  | The provider rejected the operation.                                                                                                                                                     |
| 915  | `PAYMENT_SUBSCRIPTION_PROVIDER_UNAVAILABLE` | 503  | Temporary failure. Retry later.                                                                                                                                                          |
| 916  | `PAYMENT_SUBSCRIPTION_REQUIRED`             | 400  | **Deposits only:** the user does not have a confirmed subscription for that payment method. Create the subscription first, and check that the `payer.id` is the same as in the creation. |

A creation without `payer.id` responds with HTTP 400:

```json
{"code": 201, "type": "BEAN_VALIDATION_ERROR", "description": "Field validation error. Check details", "details": ["payerIdentified: payer.id is required"]}
```

In addition, the general API v3 errors apply (headers, signature, credentials, IP, country, payment method not enabled).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tupayonline.com/english/api-documentation/deposit/subscriptions-process.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
