Crear una solicitud de pago por e-mail
Pruebe el servicio web Charge/CreatePaymentOrder desde nuestro playground: Charge/CreatePaymentOrder .
Solicitud
Parámetro | Obligatorio | DESCRIPCIÓN |
---|---|---|
channelOptions.channelType | Sí | Parámetro que permite definir el canal de emisión de la solicitud de pago. Su valor debe ser MAIL . |
channelOptions.mailOptions | Sí | Objeto json que permite definir los parámetros específicos para la creación de una solicitud de pago por e-mail. |
channelOptions.mailOptions.recipient | Sí | Dirección de e-mail del destinatario. |
channelOptions.mailOptions.bcc | No | Lista de destinatarios adicionales. Estos destinatarios no son visibles para el destinatario principal (destinatario). Utilice el punto y coma ";" como separador entre cada dirección |
channelOptions.mailOptions.subject | No | Permite personalizar el asunto del e-mail. Este parámetro es obligatorio a menos que indique un nombre de plantilla válido en el parámetro channelOptions.mailOptions.template . |
channelOptions.mailOptions.body | No | Permite personalizar el cuerpo del e-mail enviado. Si el parámetro se deja vacío, se aplicará la plantilla predeterminada. |
channelOptions.mailOptions.template | No | Nombre de la plantilla a utilizar para generar el e-mail. Il est nécessaire que le modèle existe dans le Back Office pour que cela fonctionne Chaque modèle d’e-mail est associé à une langue (ou locale).Pour utiliser un modèle vous devez vous assurer de transmettre la bonne langue dans le paramètre locale Si no se encuentra la plantilla se devolverá un error. Si definió un valor en los parámetros subject y body , se ignorará la plantilla. |
expirationDate | No | Date de validité de l'ordre au format ISO-8601. Ne peut pas être antérieure à la date courante et ne peut pas dépasser 90 jours. Si ce paramètre n'est pas envoyé, la valeur appliquée sera celle de la boutique. Ex : 2021-10-05T21:59:59+00:00 |
locale | No | Código que representa el nombre del idioma y compuesto por el código del idioma (ISO 639-1) seguido del código del país (ISO 3166 alfa-2), separados por el carácter "_". Le permite definir el idioma de las páginas de pago y el correo electrónico de confirmación. Si no se define este parámetro, se utilizará el idioma de la tienda. Por ejemplo: "fr_FR", "es_CO", "en_EN", "pt_BR" |
merchantComment | No | Comentario opcional. |
amount | Sí | Monto a pagar, expresado en su unidad monetaria más pequeña (el centavo para el euro). |
currency | Sí | Moneda del pago Código ISO 4217 alpha-3 Ejemplo: "EUR" para euro. |
orderId | No | Referencia del pedido. |
taxAmount | No | Monto de los impuestos para todo el pedido, expresado en su unidad monetaria más pequeña (el centavo para el euro). |
taxRate | No | Tipo de impuesto aplicado a todo el pedido. El valor debe ser el porcentaje a aplicar (21 para 21 %). |
transactionOptions.cardOptions.manualValidation | No | Permite definir si la validación de la transacción es manual. Valores posibles: |
transactionOptions.cardOptions.captureDelay | No | Indica el plazo, en días, antes de su captura. |
strongAuthentication | No | Permite habilitar o deshabilitar la autenticación fuerte durante el pago. Valores posibles: |
paymentReceiptEmail | No | Dirección de e-mail para el envío del ticket de pago al comprador. Requiere la activación de la regla de notificación: "E-mail de confirmación de pago destinado al comprador". |
dataCollectionForm | No | Uso del formulario de recogida de datos. Valores posibles: |
customer | No | Objeto que contiene los datos del comprador. |
formAction | No | permite definir el tipo de comportamiento que desea al crear la transacción. |
paymentMethodToken | No | Token del medio de pago que se utilizará para el pago. |
metadata | No | Valores personalizados vinculados a la transacción, en formato json. |
Respuesta
El objeto answer contendrá los siguientes parámetros:
Parámetro | DESCRIPCIÓN |
---|---|
paymentOrderId | ID de la solicitud de pago. |
paymentURL | URL de pago. |
paymentOrderStatus | Estado de la solicitud de pago. |
creationDate | Fecha y hora de creación de la solicitud de pago. |
updateDate | Fecha y hora de modificación de la solicitud de pago. |
channelDetails.channelType | Canal de transmisión de la solicitud de pago. Establecido en MAIL . |
channelDetails.mailDetails.recipient | Dirección de e-mail del destinatario. |
channelDetails.mailDetails.subject | Asunto del e-mail enviado. |
channelDetails.mailDetails.body | Cuerpo del e-mail enviado. |
channelDetails.mailDetails.template | Nombre de la plantilla utilizada. |
channelDetails.mailDetails.bcc | Lista de los destinatarios en copia oculta. |
message | Mensaje que incluye el enlace de pago, redactado en el idioma de la configuración regional. |
amount | Monto a pagar, expresado en la unidad más pequeña de la moneda utilizada. |
currency | Moneda del pago. Código ISO 4217 alpha-3. |
locale | Código que representa el nombre del idioma, compuesto por el código del idioma (ISO 639-1) seguido del código del país (ISO 3166 alpha-2), separados por el carácter "_". |
strongAuthentication | Permite habilitar o deshabilitar la autenticación fuerte durante el pago. |
orderId | Referencia del pedido. |
paymentReceiptEmail | Dirección de e-mail para el envío del ticket de pago al comprador. |
taxAmount | Monto de los impuestos para todo el pedido, expresado en su unidad monetaria más pequeña. |
taxRate | Tipo de impuesto aplicado a todo el pedido. |
expirationDate | Fecha de vencimiento de la solicitud en formato ISO-8601. |
dataCollectionForm | Uso del formulario de recogida de datos. |
merchantComment | Comentario. |
transactionDetails.cardDetails.manualValidation | Modo de validación de la transacción. |
transactionDetails.cardDetails.captureDelay | Plazo de captura. |
customer | Objeto que contiene los datos del comprador. |
formAction | permite definir el tipo de comportamiento que desea al crear la transacción. |
paymentMethodToken | Token del medio de pago que se utilizará para el pago. |
metadata | Valores personalizados vinculados a la transacción, en formato json. |
Ejemplo de respuesta
{ "webService": "Charge/CreatePaymentOrder", "version": "V4", "applicationVersion": "5.5.0", "status": "SUCCESS", "answer": { "paymentOrderId": "fd8f6060f824427ba687d0161e46af8f", "paymentURL": "https://secure.lyra.com/t/328zq5so", "paymentOrderStatus": "RUNNING", "creationDate": "2020-03-31T15:06:49+00:00", "updateDate": null, "amount": 200050, "currency": "EUR", "locale": "en_GB", "strongAuthentication": "AUTO", "orderId": "myOrderId-999999", "channelDetails": { "channelType": "MAIL", "mailDetails": { "subject": "Your payment order", "body": "<b>Message sent by DEMO STORE</b> <p>Dear customer, </p> <p>This e-mail is a payment order of EUR 2, 000.50 valid until 01/04/2020. To confirm, please click on the link below : </p> <p>https://secure.lyra.com/t/w5izg024</p> <p>In case of problems, or if this message is not correctly displayed, please contact support@demostore.com.</p>", "template": null, "recipient": "sample@example.com", "bcc": null, "_type": "V4/MailDetails" }, "smsDetails": null, "whatsAppDetails": null, "_type": "V4/ChannelDetails" }, "paymentReceiptEmail": "sample@example.com", "taxRate": null, "taxAmount": null, "expirationDate": "2020-04-20T18:13:26+00:00", "transactionDetails": { "cardDetails": { "manualValidation": "NO", "captureDelay": 0, "_type": "V4/CardDetails" }, "_type": "V4/PaymentOrderTransactionDetails" }, "dataCollectionForm": false, "merchantComment": null, "message": "<b>Message sent by DEMO STORE</b> <p>Dear customer, </p> <p>This e-mail is a payment order of EUR 2, 000.50 valid until 01/04/2020. To confirm, please click on the link below : </p> <p>https://secure.lyra.com/t/w5izg024</p> <p>In case of problems, or if this message is not correctly displayed, please contact support@demostore.com.</p>", "_type": "V4/PaymentOrder" }, "ticket": null, "serverDate": "2020-03-31T15:06:49+00:00", "applicationProvider": "PAYZEN", "metadata": null, "_type": "V4/WebService/Response" } }
Manejo de errores
El servicio web Charge/createPaymentOrder devolverá un error en los siguientes casos:
Código | DESCRIPCIÓN |
---|---|
INT_009 | El formato del campo amount no es válido o el campo no se ha transmitido. |
INT_010 | El formato del campo currency no es válido o el campo no se ha transmitido. |
INT_050 | El parámetro strongAuthentication no es válido. |
INT_841 | Falta el objeto mailOptions . |
INT_850 | Falta el parámetro channelOptions.mailOptions.recipient . |
INT_856 | El parámetro locale no es válido. |
INT_858 | El parámetro taxRate no es válido. |
INT_869 | El parámetro taxAmount no es válido. |
PSP_519 | Moneda desconocida. |
PSP_606 | Moneda no admitida por la afiliación. |
PSP_1007 | La fecha de vencimiento de la solicitud de pago no puede ser anterior a la fecha actual ni exceder los 90 días. |
PSP_1015 | No hay ningún formulario de recolección de datos para esta tienda. |
PSP_1018 | No se puede utilizar el formulario de recolección de datos para la moneda solicitada. |
PSP_1022 | La plantilla especificada en la solicitud no existe para la configuración regional solicitada. |
Casos de uso
Hay 3 casos de uso disponibles:
- enviar un e-mail utilizando la plantilla “predeterminada” definida por la plataforma de pago,
- Enviar un e-mail utilizando una plantilla personalizada, definida en el Back Office del vendedor,
- enviar un e-mail personalizando su contenido directamente en la solicitud.
Ejemplo de solicitud que utiliza la plantilla predeterminada
El vendedor desea enviar una solicitud de pago utilizando el asunto y el mensaje definidos como predeterminados por la plataforma de pago.
Para ello, no transmita los campos subject , body ni template .
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "PEN", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_PE", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_AR", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "es_CO", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "BRL", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient": "sample@example.com" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "locale": "pt_BR", "dataCollectionForm": "false" }
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
Ejemplo de solicitud utilizando una plantilla de e-mail personalizada
El vendedor ha creado una plantilla personalizada en una configuración regional específica desde el
Para hacerlo, utilice el campo template para transmitir el nombre de la plantilla a utilizar.
No transmita los campos body ni subject , no se tomarán en cuenta.
No es necesario transmitir el campo locale , su valor se deducirá a partir de la plantilla que se utilizará.
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_fr" } }, "paymentReceiptEmail" : "sample@example.com", "expirationDate" : "2020-04-20T20:13:26+02:00", "dataCollectionForm" : "false" }
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_en" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "PEN", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_es" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_es" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_es" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "BRL", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "template":"template_pt" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
Ejemplo de solicitud para enviar un mensaje personalizado
El vendedor desea personalizar el asunto y el mensaje del e-mail en su solicitud.
Para ello, no transmita el campo template .
Utilice los campos subject y body .
Para personalizarlos, las siguientes variables están a su disposición:
Valor | DESCRIPCIÓN |
---|---|
%url% | URL de la solicitud de pago. Si falta esta variable, el enlace de pago se agregará automáticamente al final del mensaje. |
%amount% | Monto y moneda del pago |
%start_date% | Fecha de creación de la solicitud de pago. Permite indicar el inicio del periodo de validez de la solicitud de pago. |
%end_date% | Permite indicar el fin del periodo de validez de la solicitud de pago. |
%shop_name% | Nombre de su tienda como se define en el Back Office |
%reference% | Referencia del pedido |
%shop_url% | URL de su tienda |
%shop_contact% | Dirección de e-mail del “administrador de la tienda” como se define en el Back Office |
En la respuesta, estas variables se reemplazarán por su valor.
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Votre commande %reference% sur %shop_name%", "body":"Bonjour, <br/>cet e-mail comporte un lien de paiement d'un montant de %amount% valable jusqu'au %end_date%.<br/>Pour confirmer le paiement, cliquez sur le lien suivant: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 1500, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Your payment order %reference% from %shop_name%", "body":"Dear customer, <br/>this is a payment order of %amount% valid until %end_date%.<br/>To confirm, please click on the link below: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 1500, "currency": "PEN", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Su solicitud de pago %reference% por %shop_name%", "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 20000, "currency": "ARS", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Su solicitud de pago %reference% por %shop_name%", "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 100000, "currency": "COP", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Su solicitud de pago %reference% por %shop_name%", "body":"Hola, <br/>Este correo electrónico contiene una solicitud de pago por un importe de %amount% válida hasta el %end_date%.<br/> Para confirmar el pago, haga clic en el enlace siguiente: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
{ "amount": 200050, "currency": "EUR", "orderId": "myOrderId-999999", "channelOptions": { "channelType": "MAIL", "mailOptions": { "recipient":"sample@example.com", "subject": "Sua oferta de pagamento %reference% por %shop_name%", "body":"Caro cliente, <br/>Este e-mail contém uma ordem de pagamento no valor de %amount% válida até %end_date%.<br/> Para confirmar o pagamento, favor clicar sobre o link seguinte: %url%" } }, "paymentReceiptEmail": "sample@example.com", "expirationDate": "2020-04-20T20:13:26+02:00", "dataCollectionForm": "false" }
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
/** * I initialize the PHP SDK */ require_once __DIR__ . '/vendor/autoload.php'; require_once __DIR__ . '/keys.php'; require_once __DIR__ . '/helpers.php'; /** * Initialize the SDK * see keys.php */ $client = new Lyra\Client(); /** * I create a formToken */ $store = array("amount" => 250, "currency" => "EUR", "orderId" => uniqid("MyOrderId"), "customer" => array( "email" => "sample@example.com" )); $response = $client->post("V4/Charge/CreatePayment", $store); /* I check if there are some errors */ if ($response['status'] != 'SUCCESS') { /* an error occurs, I throw an exception */ display_error($response); $error = $response['answer']; throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage']); } /* everything is fine, I extract the formToken */ $formToken = $response["answer"]["formToken"]; ?>
Nota
Si se especifica la configuración regional en la solicitud, el enlace de pago y la fecha de vencimiento de la solicitud se traducirán al idioma solicitado.
Asegúrese de redactar el contenido del e-mail en el idioma correcto.