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

# API de Autorización con Yape

> Inicia cobros con Yape usando el API de autorización de PayIn.

Usa este flujo para procesar pagos ecommerce con Yape desde el API de autorización de PayIn.

**POST /charges** `endpoint`

> [!NOTE]
>
> Este flujo utiliza el mismo endpoint base de autorización. Revisa los ambientes y la configuración general en el [Overview](https://docs.pay-me.com/payin/autorizacion.md).

***

## Características del flujo

> [card] Tipo de flujo
>
> Síncrono.

> [card] Método de pago
>
> Permite procesar cobros ecommerce con billetera Yape.

> [card] Validación final
>
> La confirmación del resultado debe realizarse desde backend.

> [card] Notificación opcional
>
> Puedes enviar un `callback_url` para recibir una notificación host to host.

***

## Consideraciones

> [!NOTE]
>
> Este flujo requiere el número celular afiliado a Yape y el código OTP generado por la billetera.

> [!NOTE]
>
> Si necesitas consultar el estado de una operación luego de autorizarla, revisa el [API de Consulta con Yape](https://docs.pay-me.com/payin/consulta-yape.md).

> [!WARNING]
>
> No marques una orden como pagada solo con validaciones del frontend. Usa la respuesta backend o la consulta posterior para confirmar el estado final.

***

## Request

> [!NOTE]
>
> Antes de consumir este endpoint, solicita tu `Access Token` en [Autenticación](https://docs.pay-me.com/autenticacion.md#param-post-token).

### Headers

| Campo | Descripción | Valor | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `Authorization` | Token Bearer obtenido desde autenticación | `Bearer {access_token}` | String | SI |
| `Content-Type` | Formato del request | `application/json` | String | SI |
| `ALG-API-VERSION` | Versión del API | `1709847567` | String | SI |

```bash theme={"system"}
Authorization: Bearer {access_token}
Content-Type: application/json
ALG-API-VERSION: 1709847567
```

***

### Body

#### Objeto raíz del request

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `action` | Acción a ejecutar | `authorize` | String | SI |
| `channel` | Canal de la operación | `ecommerce` | String | SI |
| `merchant_code` | Código del comercio | `your_merchant_code` | String | SI |
| `merchant_operation_number` | Identificador único de la operación en el comercio. **Debe ser diferente en cada transacción.** | `5974484` | String | SI |
| `payment_method` | Objeto con la información del método de pago | Object | Object | SI |
| `payment_details` | Objeto con el detalle del pago y datos del cliente | Object | Object | SI |

***

#### Objeto `payment_method`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `method_name` | Nombre del método de pago | `YAPE` | String | SI |
| `method_details` | Objeto con la información específica del pago con Yape | Object | Object | SI |

***

#### Objeto `payment_method.method_details`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `callback_url` | URL donde se realizará la notificación host to host (server to server) | `https://pay-me.com/callback` | String | NO |
| `phone` | Objeto con la información del titular de Yape | Object | Object | SI |
| `otp` | Código OTP de la billetera Yape | `557454` | String | SI |

> [!NOTE]
>
> Si envías `callback_url`, asegúrate de que sea una URL backend accesible para recibir confirmaciones server to server.

***

#### Objeto `payment_method.method_details.phone`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `country_code` | Código del país del teléfono | `+51` | String | SI |
| `subscriber` | Número del teléfono | `969929157` | String | SI |

***

#### Objeto `payment_details`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `amount` | Monto de la operación en centavos | `15000` | String | SI |
| `currency` | Código de la moneda | `604` | String | SI |
| `billing` | Datos de facturación | Object | Object | SI |
| `shipping` | Datos de envío | Object | Object | SI |
| `customer` | Datos del cliente | Object | Object | SI |
| `product_details` | Lista de productos asociados a la operación | `[]` | Array | SI |

> [!NOTE]
>
> Para `billing`, `shipping` y `customer`, usa la estructura ecommerce estándar con `first_name`, `last_name`, `email`, `phone` y `location`.

***

### Ejemplo de request

```json theme={"system"}
{
  "action": "authorize",
  "channel": "ecommerce",
  "merchant_code": "your_merchant_code",
  "merchant_operation_number": "5974484",
  "payment_method": {
    "method_name": "YAPE",
    "method_details": {
      "callback_url": "https://pay-me.com/callback",
      "phone": {
        "country_code": "+51",
        "subscriber": "969929157"
      },
      "otp": "557454"
    }
  },
  "payment_details": {
    "amount": "15000",
    "currency": "604",
    "billing": {
      "first_name": "Cliente",
      "last_name": "Ejemplo",
      "email": "correo@dominio.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "shipping": {
      "first_name": "Cliente",
      "last_name": "Ejemplo",
      "email": "correo@dominio.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "customer": {
      "first_name": "Cliente",
      "last_name": "Ejemplo",
      "email": "correo@dominio.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "product_details": []
  }
}
```

***

## Response

### Objeto `transaction`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `transaction_id` | Identificador único de la transacción | `5hk8rwa3h3cq9oyfs3a28v1ms` | String | SI |
| `channel` | Canal por el cual se realizó la transacción | `ecommerce` | String | SI |
| `state` | Estado actual de la transacción | `AUTORIZADO` | String | SI |
| `state_reason` | Observación o descripción del estado actual | `Pago exitoso con Yape` | String | SI |
| `amount` | Monto de la transacción | `15000` | String | SI |
| `currency` | Código de la moneda de la operación | `604` | String | SI |
| `payment_method` | Objeto con información del método de pago usado en la transacción | Object | Object | SI |
| `processor_response` | Resultado devuelto por la procesadora | Object | Object | NO |
| `additional_fields` | Datos adicionales enviados en el request | Object | Object | NO |
| `lifecycle` | Historial de estados por los que pasó la transacción | Array | Array | SI |

> [!NOTE]
>
> `state` puede devolver valores como `AUTORIZADO`, `DENEGADO` o `INVALIDO`, según el resultado de la autorización. En el historial `lifecycle` también pueden aparecer estados intermedios como `REGISTRADO` o `PENDIENTE`.

> [!WARNING]
>
> No uses `meta.status.code` como validador de autorización o denegación del pago. Ese código solo indica si el servicio procesó o respondió correctamente; el resultado del pago se valida con `transaction.state` y, como respaldo, desde backend con consulta o notificación.

***

### Objeto `transaction.payment_method`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `method_name` | Nombre del método de pago usado en la transacción | `YAPE` | String | SI |
| `method_details` | Objeto con información detallada relacionada al método | Object | Object | SI |

***

### Objeto `transaction.payment_method.method_details`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `phone` | Objeto con la información del teléfono del cliente Yape | Object | Object | SI |
| `masked_pan` | Tarjeta enmascarada usada en la transacción | `411111********1111` | String | NO |
| `brand` | Marca de la tarjeta usada en la transacción | `VISA` | String | NO |
| `bin` | BIN de la tarjeta usada en la transacción | `411111` | String | NO |
| `last_pan` | Últimos 4 dígitos de la tarjeta usada en la transacción | `9268` | String | NO |
| `card_type` | Tipo de tarjeta | `DEBIT` | String | NO |
| `card_country` | País de la tarjeta | `PE` | String | NO |
| `issuer` | Banco emisor de la tarjeta | `BANCO DE CREDITO DEL PERU - BCP` | String | NO |

***

### Objeto `transaction.payment_method.method_details.phone`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `country_code` | Código del país del teléfono de Yape | `+51` | String | SI |
| `subscriber` | Número de teléfono de Yape | `969929157` | String | SI |

***

### Objeto `transaction.processor_response`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `authorization_code` | Código de autorización | `055552` | String | NO |
| `brand_transaction_id` | ID de la transacción ante la marca | `100B` | String | NO |
| `result_message` | Mensaje del resultado de la autorización | Object | Object | NO |

> [!NOTE]
>
> Este objeto puede mostrarse cuando la transacción llega a estados como `AUTORIZADO`, `DENEGADO` o `EXTORNADO`.

***

### Objeto `transaction.processor_response.result_message`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `code` | Código del resultado de la autorización | `00` | String | NO |
| `description` | Descripción del resultado de la autorización | `Approval and completed successfully` | String | NO |

***

### Objeto `transaction.lifecycle`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `state` | Estado registrado en el historial | `AUTORIZADO` | String | SI |
| `date` | Fecha del cambio de estado | Object | Object | SI |

> [!NOTE]
>
> En `lifecycle` puedes recibir estados intermedios como `REGISTRADO` o `PENDIENTE` antes del resultado final.

***

### Objeto `transaction.lifecycle[].date`

| Campo | Descripción | Ejemplo | Tipo | Obligatorio |
| :- | :- | :- | :- | :- |
| `utc_time` | Fecha en UTC | `2024-03-12T22:49:36.018Z` | String | SI |
| `unix_time` | Fecha en unix time | `1710282940` | Integer | SI |

***

### Ejemplo de response

```json theme={"system"}
{
  "success": "true",
  "action": "authorize",
  "merchant_code": "your_merchant_code",
  "merchant_operation_number": "2391645",
  "transaction": {
    "transaction_id": "5hk8rwa3h3cq9oyfs3a28v1ms",
    "channel": "ecommerce",
    "state": "AUTORIZADO",
    "state_reason": "Pago exitoso con Yape",
    "amount": "15000",
    "currency": "604",
    "payment_method": {
      "method_name": "YAPE",
      "method_details": {
        "phone": {
          "country_code": "+51",
          "subscriber": "969929157"
        },
        "masked_pan": "411111********1111",
        "brand": "VISA",
        "bin": "411111",
        "last_pan": "9268",
        "card_type": "DEBIT",
        "card_country": "PE",
        "issuer": "BANCO DE CREDITO DEL PERU - BCP"
      }
    },
    "processor_response": {
      "authorization_code": "055552",
      "brand_transaction_id": "100B",
      "result_message": {
        "code": "00",
        "description": "Approval and completed successfully"
      }
    },
    "additional_fields": null,
    "lifecycle": [
      {
        "state": "REGISTRADO",
        "date": {
          "utc_time": "2024-03-12T22:49:36.018Z",
          "unix_time": 1710282940
        }
      },
      {
        "state": "PENDIENTE",
        "date": {
          "utc_time": "2024-03-12T22:49:36.018Z",
          "unix_time": 1710282940
        }
      },
      {
        "state": "AUTORIZADO",
        "date": {
          "utc_time": "2024-03-12T22:49:36.018Z",
          "unix_time": 1710282940
        }
      }
    ]
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Procesado correctamente"
        }
      ]
    }
  }
}
```

***

## Buenas prácticas

* Valida siempre el resultado desde backend.
* Asegúrate de enviar un `merchant_operation_number` único por transacción.
* Verifica que el `otp` corresponda al número Yape enviado en `phone`.
* Usa `callback_url` si tu operación necesita confirmación server to server.
* No asumas que los campos opcionales de tarjeta dentro de `transaction.payment_method.method_details` siempre estarán presentes.
* Conserva `transaction_id` y `merchant_operation_number` para soporte y conciliación.

***

## Errores comunes

> [card] OTP inválido o vencido
>
> Si el OTP no corresponde al intento de pago vigente, la transacción puede ser rechazada o marcada como inválida.

> [card] Validación incompleta
>
> No tomes decisiones de negocio basándote solo en la interacción del usuario; confirma siempre el estado final desde backend.

***

## Siguiente paso

> [card] [Api de Consulta con Yape](https://docs.pay-me.com/payin/consulta-yape.md)
>
> Revisa cómo consultar el estado de una operación procesada con Yape.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.