Send a Pay-by-Link

Endpoints

HTTP Method	API URL	API Version
POST	https://connect2.payxpert.com/payment/{customerToken}/send-pay-by-link	>= 002.74

This call permits a merchant to (re)send a prepared payment’s link to the customer. Any prepared payment can be sent this way, and the call can be repeated to send the link again, on another channel or to another recipient: the channel, recipient and language are given on each call rather than held on the payment.

Note that the token that identifies the payment is part of the URL (the string {customerToken} in the URL must be replaced by the customerToken value returned by the initial payment prepare call — not the merchantToken).

When the payment was prepared without a timeOut, the first send applies a default validity to it, so the link stays usable long enough for the customer to complete the payment. Two points are worth noting:

The validity is counted from the moment the payment was prepared, not from the moment the link is sent. A payment prepared before that default validity elapsed has therefore already expired, and sending its link fails with code 501.
The change is permanent: the payment keeps that timeOut afterwards. To use a different validity, set timeOut on the payment prepare call, which this endpoint then leaves untouched.

The information for the request is serialized in JSON format and transmitted in the body of the request.

Accepted parameters

Name	Type	Description	Required
apiVersion	String(8)	API version to be used (default 002.74). None of the parameters below depend on the version, so it may be left out.	no
channel	String(16)	Channel used to deliver the link to the customer. Only `EMAIL` is currently supported.	yes
email	String(100)	Address the link is sent to. When omitted, the `shopper.email` transmitted in the prepare call is used.	no
language	String(10)	Language of the customer link email (ISO code, e.g. `en`, `fr`, `es`). When omitted, or when the requested language is not supported, the service default of `en` is used. Note that this is a service-wide default and not the default language configured on the account.	no

Response

When the request is accepted, the body of the response to a send pay-by-link request is in JSON format.

The following fields are present in the response:

Name	Type	Description	API Version
code	String(3)	API response code (see below for possible values)	>= 002.74
message	String(255)	Human readable message associated with the code	>= 002.74

Response codes

Response code	Response Message
200	Request processed successfully
401	Missing parameter in request (the body is missing, or `channel` is absent)
402	Error during JSON deserialization of parameter (the body is not valid JSON)
500	Error handling the request (e.g. the link could not be sent)
501	Incorrect data in submitted request (`channel` not supported, `email` malformed, or the payment is expired or already paid)

{
    "code": "200",
    "message": "Request processed successfully"
}

Other HTTP statuses

Two cases are signalled through the HTTP status rather than through the code field above:

HTTP status	Meaning
404	No payment matches the given `customerToken`, or it belongs to another merchant. This case produces no JSON body, so the `code` field must not be relied upon to detect it.
429	Too many pay-by-link emails were sent recently, to this recipient or from this account. Unlike 404, this case still returns the usual JSON body, with `code` 501 and a message describing which limit was hit.

Code samples

Java


  // Send the link of an already prepared payment to the customer by email
  SendPayByLinkRequest request = new SendPayByLinkRequest();
  request.setCustomerToken("<customerToken from the prepare response>");
  request.setChannel(PayByLinkChannel.EMAIL);
  request.setEmail("customer@example.com");
  request.setLanguage(C2PLang.EN);

  // Validate the request. Worth doing for the email address in particular: the service rejects a
  // malformed one with code 501, whereas this names the offending field before the call is made
  try {
    request.validate();
  } catch (Exception e) {
    logger.error("Ooops, an error occurred validating the pay-by-link request: " + e.getMessage());
    // Handle the error...
  }

  // Instantiate the client and send the request
  // Second argument is the originator ID, third one is the associated API key
  Connect2payClient c2p = new Connect2payClient("https://connect2.payxpert.com", "123456", "GreatP4ssw0rd");
  SendPayByLinkResponse response = null;
  try {
    response = c2p.sendPayByLink(request);
  } catch (Exception e) {
    logger.error("Ooops, an error occurred sending the pay-by-link: " + e.getMessage());
    // Handle the error...
  }

  if (response != null && ResultCode.SUCCESS.equals(response.getCode())) {
    // The link was sent successfully
  } else {
    // Handle the failure
  }

Copy to Clipboard