Enviar una solicitud
Siga estos pasos para enviar una solicitud a Web-Services API para una operación de transacción:
Paso 1: Verifique la conectividad del motor de pagos
Antes de enviar cualquier solicitud, verifique su conectividad con el motor de pagos. Para comprobarlo, acceda a la siguiente URL a través de un explorador web: https://gateway-na.americanexpress.com/api/rest/version/1/information. Si el intento de conexión tiene éxito y el motor de pagos procesa las solicitudes, la página del explorador muestra {"status":"OPERATING"}.
Paso 2: Configure su método de autenticación
El motor de pagos admite dos métodos de autenticación: certificados Secure Sockets Layer (SSL) y contraseñas.
- Seleccione el método que mejor se adapte a su modelo de negocio e impleméntelo.
Paso 3: Cree la solicitud de transacción
Crear el cuerpo de la solicitud es un paso crítico en su integración. Los campos del cuerpo de la solicitud recopilados del formulario dirigido al pagador y generados dentro de su sistema se envían a la URL de API en formato REST JSON. Dependiendo de la operación de transacción, se utiliza uno de los siguientes métodos HTTP en la URL:
- POST se utiliza cuando desea que el sistema cree una nueva colección.
- PUT se utiliza cuando desea agregar o modificar un miembro de una colección.
- GET se utiliza para recuperar operaciones.
Formatear los datos del cuerpo de la solicitud desde los formularios
Independientemente del idioma seleccionado en el fragmento de código, es importante que su integración formatee correctamente los datos de la solicitud de transacción. En muchos idiomas, es común recibir los datos del formulario que un pagador ha ingresado, como una matriz.
En la mayoría de los casos, puede utilizar una matriz para almacenar los nombres y valores de cada campo que desee pasar al motor de pagos y formatearlo como se muestra en el siguiente fragmento. Este fragmento de código completa dos funciones críticas para dar como resultado un cuerpo de solicitud de transacción con el formato correcto:
- Garantiza que no se agreguen campos vacíos al cuerpo de la solicitud de transacción.
- Formatea los datos según el protocolo JSON.
Cómo convertir datos de formulario a
(, ) CambiarSeleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Paso 4: Enviar la solicitud de transacción
Siga estos pasos para asegurarse de que el cuerpo de la solicitud de transacción se envíe de forma segura al motor de pagos:
Establecer datos de autenticación
La API requiere que cada solicitud de transacción se autentique correctamente. Si utiliza la contraseña de API como método de autenticación, el siguiente fragmento explica cómo proporcionar los datos de autenticación, como el ID del negocio o la contraseña de API, o ambos, como un encabezado, en cada solicitud de transacción.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Establecer encabezados HTTP
Los encabezados HTTP proporcionan información de metadatos sobre la solicitud de transacción enviada al motor de pagos. Además de los encabezados de autenticación que se tratan en las secciones anteriores, el siguiente fragmento muestra cómo configurar los encabezados HTTP obligatorios para cada solicitud de transacción.
Los encabezados de Content-Length y de Content-Type son críticos ya que indican al servidor web la cantidad y el tipo de bytes de datos, identificados por un tipo MIME.
La codificación de caracteres de su solicitud debe incluir el formato ISO-8859-1 o UTF-8. El motor de pagos rechaza cualquier carácter que no pueda representarse en uno de los formatos admitidos. Si no se especifica, el motor de pagos establece de forma predeterminada la codificación ISO-8859-1. A continuación se muestra un ejemplo del encabezado de tipo de contenido.
"Content-Type: application/json; charset=UTF-8"
Para configurar el encabezado, utilice el siguiente código.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Utilice un método HTTP específico
Es importante utilizar un método HTTP específico como POST, PUT o GET para cada transacción. Todas las operaciones básicas realizadas a través de la API utilizan los métodos HTTP POST o PUT, excepto CHECK GATEWAY y varias operaciones de recuperación:
El método HTTP PUT actualiza el miembro especificado de la colección; o si no existe, crea un nuevo miembro. Por ejemplo, considere una solicitud donde el valor del URI de solicitud es: http://example.com/version/v1/merchant/m1/order/o1/transaction/t1
En el URI, t1 es miembro del recurso de colección o1. Si t1 existe, la solicitud modifica el recurso t1 y, si no, crea un nuevo miembro t1.
El método HTTP GET recupera una representación del miembro abordado de la colección. Por ejemplo, considere una solicitud donde el valor del URI de solicitud es: http://example.com/version/v1/merchant/m1/order/o1/transaction/t1
La solicitud recupera el elemento t1 del recurso de colección o1.
- El método HTTP POST crea una nueva colección. En las API del motor de pagos, se utiliza principalmente para operaciones que crean un nuevo conjunto de datos, como la operación CREATE SESSION o PAYMENT OPTIONS INQUIRY.
El siguiente fragmento de código muestra cómo utilizar el método HTTP POST.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
El siguiente fragmento de código muestra cómo utilizar el método HTTP PUT.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Definir la URL de destino
La URL utilizada para enviar la solicitud de transacción varía para cada operación de transacción. En el siguiente fragmento, la función calcula la URL a partir de su configuración, establece la versión y los valores de los recursos del negocio y, finalmente, agrega una lista personalizada de recursos y sus identificadores.
Estos componentes personalizados representan el pedido y los recursos de transacción. Para obtener más información sobre el formato de URL para cada operación, consulte las operaciones individuales en la Referencia de API.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Configuración de la dirección URL para enviar la transacción
El siguiente fragmento de código muestra cómo configurar la URL para enviar una transacción.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Verificar el certificado SSL de un motor de pagos
Si está utilizando el método autenticación de certificado SSL, valide el certificado SSL del motor de pagos. Validar el certificado SSL cuando envía la solicitud de transacción evita ataques maliciosos y otros posibles problemas de seguridad. El siguiente fragmento de código muestra cómo verificar el certificado SSL.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Configurar un servidor proxy
En algunos entornos de red, puede ser necesario enviar la solicitud de transacción a través de un servidor proxy. Comuníquese con su administrador de red o proveedor de alojamiento web para obtener información sobre si se requiere un servidor proxy para su integración. El siguiente fragmento de código muestra cómo configurar un proxy y su autenticación.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra
Enviar la transacción al motor de pagos
Envíe la solicitud de transacción con el formato correcto al motor de pagos y espere una respuesta. El siguiente fragmento de código muestra cómo enviar una transacción al motor de pagos.
Seleccione protocolo e idioma para ver el fragmento de código.De: Descarga de código de muestra