API de Autorización con Yape - Alignet Integration Docs

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

POST /charges

endpoint

Este flujo utiliza el mismo endpoint base de autorización. Revisa los ambientes y la configuración general en el Overview.

Características del flujo

Tipo de flujo

Síncrono.

Método de pago

Permite procesar cobros ecommerce con billetera Yape.

Validación final

La confirmación del resultado debe realizarse desde backend.

Notificación opcional

Puedes enviar un callback_url para recibir una notificación host to host.

Consideraciones

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

Si necesitas consultar el estado de una operación luego de autorizarla, revisa el API de Consulta con Yape.

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

Antes de consumir este endpoint, solicita tu Access Token en Autenticación.

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

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

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

Para billing, shipping y customer, usa la estructura ecommerce estándar con first_name, last_name, email, phone y location.

Ejemplo de request

{
  "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": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.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": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.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": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.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

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.

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

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

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

{
  "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

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.

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

Api de Consulta con Yape

Revisa cómo consultar el estado de una operación procesada con Yape.

​Características del flujo

Tipo de flujo

Método de pago

Validación final

Notificación opcional

​Consideraciones

​Request

​Headers

​Body

​Objeto raíz del request

​Objeto payment_method

​Objeto payment_method.method_details

​Objeto payment_method.method_details.phone

​Objeto payment_details

​Ejemplo de request

​Response

​Objeto transaction

​Objeto transaction.payment_method

​Objeto transaction.payment_method.method_details

​Objeto transaction.payment_method.method_details.phone

​Objeto transaction.processor_response

​Objeto transaction.processor_response.result_message

​Objeto transaction.lifecycle

​Objeto transaction.lifecycle[].date

​Ejemplo de response

​Buenas prácticas

​Errores comunes

OTP inválido o vencido

Validación incompleta

​Siguiente paso

Api de Consulta con Yape

Características del flujo

Consideraciones

Request

Headers

Body

Objeto raíz del request

Objeto `payment_method`

Objeto `payment_method.method_details`

Objeto `payment_method.method_details.phone`

Objeto `payment_details`

Ejemplo de request

Response

Objeto `transaction`

Objeto `transaction.payment_method`

Objeto `transaction.payment_method.method_details`

Objeto `transaction.payment_method.method_details.phone`

Objeto `transaction.processor_response`

Objeto `transaction.processor_response.result_message`

Objeto `transaction.lifecycle`

Objeto `transaction.lifecycle[].date`

Ejemplo de response

Buenas prácticas

Errores comunes

Siguiente paso