API de Autorización con Transferencia Bancaria

Usa este flujo para iniciar pagos ecommerce con transferencia bancaria 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

Asíncrono.

Método de pago

Permite iniciar cobros ecommerce con transferencia bancaria.

Redirección

El usuario continúa el pago fuera de tu checkout.

Validación final

El resultado final debe confirmarse por backend con notificación o consulta.

Consideraciones

Este flujo requiere redirect_url para retornar al comercio cuando finalice la autorización y permite enviar callback_url para notificación host to host.

Si trabajas con redirect, revisa también las Consideraciones para métodos con Redirect.

No tomes como final la respuesta inicial del POST /charges. Confirma el resultado con Notificaciones o con Consulta.

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.	`5974483`	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	`BANK_TRANSFER`	String	SI
`method_details`	Objeto con la información específica de la transferencia bancaria	Object	Object	SI

Objeto `payment_method.method_details`

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`redirect_url`	URL donde se realizará el redirect cuando finalice la autorización	`https://pay-me.com`	String	SI
`callback_url`	URL donde se realizará la notificación host to host (server to server)	`https://pay-me.com/callback`	String	NO

redirect_url debe apuntar a una ruta de tu comercio preparada para recibir el retorno del usuario. Si envías callback_url, asegúrate de que sea accesible desde backend.

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": "5974483",
  "payment_method": {
    "method_name": "BANK_TRANSFER",
    "method_details": {
      "redirect_url": "https://pay-me.com",
      "callback_url": "https://pay-me.com/callback"
    }
  },
  "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

Para recibir la respuesta final de una autorización con redirect, toma en cuenta las Consideraciones para métodos con Redirect. La respuesta inicial normalmente deja la transacción en seguimiento.

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	`PENDIENTE`	String	SI
`state_reason`	Observación o descripción del estado actual	`Url generada para continuar con el pago`	String	SI
`continue_url`	URL para continuar el flujo del pago fuera del checkout	`https://api.dev.alignet.io/payment/continue/card/81vrxn30vja1gwcfsdng4i5g5`	String	NO
`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
`expiration_date`	Fecha en la que expirará la transacción	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 PENDIENTE o INVALIDO. continue_url y expiration_date suelen estar presentes cuando la transacción queda en estado PENDIENTE.

Objeto `transaction.payment_method`

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`method_name`	Nombre del método de pago usado en la transacción	`BANK_TRANSFER`	String	SI
`method_details`	Objeto que contiene el detalle del método de pago usado en la transacción	Object	Object	SI

Objeto `transaction.payment_method.method_details`

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`redirect_url`	URL donde se realizará el redirect cuando finalice la autorización	`https://pay-me.com`	String	SI
`callback_url`	URL donde se realizará la notificación host to host (server to server)	`https://pay-me.com/callback`	String	NO

Objeto `transaction.expiration_date`

Campo	Descripción	Ejemplo	Tipo	Obligatorio
`utc_time`	Fecha de expiración en UTC	`2024-03-12T22:49:36.018Z`	String	NO
`unix_time`	Fecha de expiración en unix time	`1711585037`	Integer	NO

Objeto `transaction.lifecycle`

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

En lifecycle puedes recibir estados como REGISTRADO, PENDIENTE e INVALIDO.

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": "PENDIENTE",
    "state_reason": "Url generada para continuar con el pago",
    "continue_url": "https://api.dev.alignet.io/payment/continue/card/81vrxn30vja1gwcfsdng4i5g5",
    "amount": "15000",
    "currency": "604",
    "payment_method": {
      "method_name": "BANK_TRANSFER",
      "method_details": {
        "redirect_url": "https://pay-me.com",
        "callback_url": "https://pay-me.com/callback"
      }
    },
    "expiration_date": {
      "utc_time": "2024-03-12T22:49:36.018Z",
      "unix_time": 1711585037
    },
    "processor_response": null,
    "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
        }
      }
    ]
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Procesado correctamente"
        }
      ]
    }
  }
}

Buenas prácticas

Confirma el resultado final por backend antes de actualizar la orden.
Asegúrate de enviar un merchant_operation_number único por transacción.
Implementa el manejo del retorno del usuario a redirect_url sin asumir que el pago terminó correctamente.
Usa callback_url si tu operación necesita confirmación server to server.
Conserva transaction_id, merchant_operation_number y continue_url para seguimiento, soporte y conciliación.

Errores comunes

Confirmación prematura

No marques una orden como pagada solo porque el usuario regresó a tu sitio o porque recibiste una respuesta inicial PENDIENTE.

Redirect incompleto

Si redirect_url no está correctamente implementado, el usuario puede completar el flujo bancario sin que tu comercio procese bien el retorno.

Siguiente paso

Api de Consulta con Transferencia Bancaria

Verifica cómo consultar el estado de una operación por transferencia bancaria.

Primeros pasos

Integración

Pagos

Gestión y Operaciones

API de Autorización con Transferencia Bancaria

Características del flujo

Tipo de flujo

Método de pago

Redirección

Validación final

Consideraciones

Request

Headers

Body

Objeto raíz del request

Objeto `payment_method`

Objeto `payment_method.method_details`

Objeto `payment_details`

Ejemplo de request

Response

Objeto `transaction`

Objeto `transaction.payment_method`

Objeto `transaction.payment_method.method_details`

Objeto `transaction.expiration_date`

Objeto `transaction.lifecycle`

Objeto `transaction.lifecycle[].date`

Ejemplo de response

Buenas prácticas

Errores comunes

Confirmación prematura

Redirect incompleto

Siguiente paso

Api de Consulta con Transferencia Bancaria

Primeros pasos

Integración

Pagos

Gestión y Operaciones

​Características del flujo

Tipo de flujo

Método de pago

Redirección

Validación final

​Consideraciones

​Request

​Headers

​Body

​Objeto raíz del request

​Objeto payment_method

​Objeto payment_method.method_details

​Objeto payment_details

​Ejemplo de request

​Response

​Objeto transaction

​Objeto transaction.payment_method

​Objeto transaction.payment_method.method_details

​Objeto transaction.expiration_date

​Objeto transaction.lifecycle

​Objeto transaction.lifecycle[].date

​Ejemplo de response

​Buenas prácticas

​Errores comunes

Confirmación prematura

Redirect incompleto

​Siguiente paso

Api de Consulta con Transferencia Bancaria

Características del flujo

Consideraciones

Request

Headers

Body

Objeto raíz del request

Objeto `payment_method`

Objeto `payment_method.method_details`

Objeto `payment_details`

Ejemplo de request

Response

Objeto `transaction`

Objeto `transaction.payment_method`

Objeto `transaction.payment_method.method_details`

Objeto `transaction.expiration_date`

Objeto `transaction.lifecycle`

Objeto `transaction.lifecycle[].date`

Ejemplo de response

Buenas prácticas

Errores comunes

Siguiente paso