Payment link purchases

Notice: This article covers processing payment link purchases via Gate and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of payment link purchases:

  • Payment link purchase—an article in the section Payment models and statuses that provides a general description of processing payment link purchases in the ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
  • Step-by-step instructions on how to perform payment link purchases via Dashboard.
  • articles of the Payment methods section containing a description of processing purchases via Payment Page with the focus on the specific processing scenarios and interaction workflows.

Overview

Payment link purchase is a payment type which uses an initial request to generate a web link that customers can click to make purchases that involve a one-time or recurring transfer of funds from the customer to the merchant. As a rule, payment link purchases are used for one-time payments with or without the authorisation hold. At the same time, if needed, payment link purchases can be used for registering COF purchases, while with certain payment methods payment links can be used for obtaining the customer's consent to registration of a COF purchase, without actual withdrawal of funds.

Purchases of this type utilise Payment Page. The payment link to open the payment form is delivered to the customer by the ecommpay payment platform via email or by the merchant using any available delivery media. The merchant chooses the payment link validity period and the payment processing scenario and specifies them in the request for initiating the payment. The validity period of the link (from the moment when the link is generated in the payment platform to the moment when the request to initiate the payment is received in the payment platform) cannot exceed 30 days, and when the link expires, the payment platform sends a corresponding callback. The merchant can also specify the payment method for making the payment. Alternatively, the merchant can allow the customer to choose one of the payment methods available in the merchant project.

Because payment link purchases are processed via Payment Page, payment requests either do not contain payment instrument data, or provide it in the form of a card token. In the latter case, the customer is required only to prove the validity of the payment instrument; there is no need to specify payment instrument details in the payment form.

As in other payment types, payment link purchase may require additional procedures such as the 3‑D Secure authentication, submission of additional payment information, or currency conversion. These procedures are performed on the side of Payment Page and require no additional effort on the merchant's web service side.

Processing scenarios

Suppose that your customer wants to make a 1379.50 USD purchase by using payment link and asks you to send the payment link to email eddington@mail.uk.

Payment processing

Figure 1. Opening payment form and entering payment details
Figure 2. Receiving the information about the payment result
  1. The web service sends to the payment platform a request with parameters that require the ecommpay platform to send the payment link to customer.
  2. The payment platform processes the request, issues the corresponding callback to merchant's web service, and sends the payment link to the email that was specified in the initial request. Standard email content is shown below. The preferable language of email is English.
  3. Customer clicks the payment link to open Payment Page. If the initial request does not contain instructions to select specific payment method, Payment Page displays payment method selection page. If the initial request specifies the payment method, Payment Page displays the page for the selected payment method.
  4. The customer enters payment details and proceeds with payment; if necessary the customer performs additional operations required to complete one or more auxiliary procedures.
  5. After payment is complete the payment platform submits a callback with the payment results to the web service; the web page with the payment result information is displayed to the customer.

Payment cancellation

  1. Merchant's web service sends a request for payment cancellation to the payment platform.
  2. The payment platform processes the request, issues the corresponding callback to merchant's web service, and sends an email to the email address that was specified in the initial request. Standard email content is shown below. The preferable language of email is English.
    Figure 3. Sample payment cancellation email


  3. Customer clicks the payment link and is presented with the payment cancellation page.

Payment link expiration

  1. The payment platform sends a callback with notification about expired payment link to the web service.
  2. If customer clicks the payment link, a page with the notification about expired payment link is displayed.
    Figure 4. Page with notification about expired payment link


Below you find the information about what the web service is required to do to complete payment.

Customising email and payment form

Email content and design

By default, the email sent to the customer includes the sender's email address (noreply@ecommpay.com), the subject line with the name of the merchant or the project used (as specified in the platform), for example, Payment Link from Cosmoshop, as well as the following information from the request to generate a payment link:

  • payment identifier (from the payment_id parameter)
  • payment amount and currency (from the amount and currency parameters, respectively)
  • payment link expiry date and time (from the best_before parameter)
  • payment description (from the description parameter)
Figure 5. Default email template

If needed, the merchant can designate a specific email address that will be shown to the customer as a sender's address, change the language and the information included in the email, or provide their own customised version of the email design and layout.

To customise the template of payment link email, contact the ecommpay technical support at support@ecommpay.com.

Payment form design

By default, the payment form displayed to the customer has the standard design provided by ecommpay. If desired, it is possible to customise the design with the application of various changes to separate payment form elements by using the corresponding design builder. With questions that do not cover the design builder capabilities, contact your account manager.

Workflow

When processing a payment link purchase by using Gate, merchant's web service is required to do the following:

  1. Send a payment link purchase request to the following endpoint /v2/payment/invoice[/card/token]/create.
  2. Receive the callback with the payment link.
  3. Receive the callback with payment result or the callback with payment link expiry notification.

In a two-step payment link purchase, you need to complete the second step which includes either capturing the authorised amount or cancelling authorisation. For more information about performing the second step in two-step purchase, see Two-step purchase.

The following diagram provides the detailed picture of payment link purchase processing.



Figure 6. Payment link purchase processing
  1. The web service sends the request for processing a payment link purchase to the specified ecommpay URL.
  2. The payment platform receives the request.
  3. The payment platform accepts and validates the request.
  4. The payment platform sends to the web service response with request receipt confirmation and validation result.
  5. The payment platform processes the request.
  6. The payment platform sends a callback with the payment link to merchant's web service.
  7. The payment platform sends an email with the payment link to customer's address. The payment link may be delivered by using merchant's web service or any other available delivery means.
  8. Customer follows the payment link.
  9. The payment platform receives the request for payment page.
  10. The payment platform processes the request.
  11. The payment platform generates Payment Page that is compliant with the project settings.
  12. Customer is presented with the generated payment form.
  13. Customer enters payment details and confirms the purchase.
  14. The payment platform receives the purchase request.
  15. The payment platform processes the request and forwards it to the payment system (or to the provider service).
  16. The payment system (or the provider service) processes the payment.
  17. The payment system (or the provider service) sends a notification with the payment result to the payment platform.
  18. The payment platform sends a callback with the payment result to the web service.
  19. The payment platform sends the payment result to Payment Page.
  20. The payment result is displayed to customer on Payment Page.

To cancel the purchase, do the following before the customer confirms the purchase:

  1. Send cancel payment request to endpoint /v2/payment/invoice/cancel.
  2. Receive the ‘payment cancelled’ callback.

The next sections describes request formats and the parameters for initiating and cancelling payment link purchases; the sections that follow also discuss payment callback formats. Information about possible statuses of this payment type can be found in the corresponding article.

Request formats

Format of payment request

When creating requests, you need to consider the following:

  1. The request is sent by using POST (HTTP) method to one of the following endpoints: /v2/payment/invoice/create or /v2/payment/invoice/card/token/create.
  2. The following objects and parameters must be specified in the request:
    • general—object with general request identification information:
      • project_id—the project ID obtained from ecommpay when onboarding
      • payment_id—payment ID that must be unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—customer ID in merchant's web service
    • payment—object with payment information:
      • amount—payment amount in minor currency units
      • currency—payment currency in the ISO-4217 alpha-3 format
      • best_before—expiry date and time of the payment link in the following format: YYYY-MM-DDThh:mm:ss±hh:mm. Keep in mind that the validity period of the payment link cannot exceed 30 days.
  3. If any token is used, you need to add it in the token parameter.
  4. To deliver payment link through ecommpay, specify the following parameters:
    • email—customer email as specified in the customer object.
    • send_email—automatic payment link delivery flag that must be set to true.
    • language—language code as specified in the customer object. The parameter is required, if customer language in not English and the corresponding template in available in the payment platform.
  5. If you need to preselect specific payment method, specify the payment method code in the force_method. (For complete list of payment methods codes, see Payment method codes.)
  6. To register a COF purchase, pass the recurring object that contains required parameters for the COF purchase being registered:
    • register—COF purchase registration flag; use true value to have the COF purchase registered.
    • type—type of the COF purchase to register, possible values:
      • C—one-click purchase
      • U—autopurchase
      • R—regular purchase
    • time—time of subsequent debiting for regular purchase in hh:mm:ss format
    • period—debiting period for regular purchase:
      • D—daily
      • W—weekly
      • M—monthly
      • Q—quarterly
      • Y—yearly

    You can also use any other additional parameters of the recurring object as specified in the API specification.

  7. If required, you can also add any other additional parameters as specified in the API specification.

Thus, a correct payment request for purchase by payment link must include project and payment IDs, signature, customer ID, payment currency and amount, payment link expiry date and time, and, if required, payment card token. If you want ecommpay to deliver payment link to your customer, you need also to specify customer email and set the automatic payment link delivery flag.

{
  "general": {
      "project_id": 1901,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm=="
  },
    "customer": {
      "id": "stapleton",
      "email": "baskerville@mail.uk"
  },
    "payment": {
      "amount": 1500,
      "currency": "GBP",
      "best_before": "2023-03-08T09:00:00+03:00"
  },
    "send_email": true,
// If card token was previously submitted:
    "token": "f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654"  
}

Format of request for payment cancellation

When creating requests, you need to consider the following:

  1. The request is sent by using POST (HTTP) method to the following endpoint: /v2/payment/invoice/cancel.
  2. The request must contain the general object with the key parameters:
    • project_id—the project ID obtained from ecommpay when onboarding
    • payment_id—ID of payment to cancel
    • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  3. If required, you can also add any other additional parameters as specified in the API specification.

Thus, a correct payment request for payment cancellation must include project and payment IDs and signature.

{
  "general": {
      "project_id": 1901,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm=="
  }
}

Callback formats

Format of callback with payment link delivery information

Callbacks with payment link delivery information use the standard format for callbacks described in greater details in Callbacks.

The following is the example of a callback with information about successful generation and delivery of a payment link for a 12.99 GBP purchase to email baskerville@mail.uk of the customer stapleton. The expiration date and time of the payment link is October 11, 2020, 11:50.

Figure 7. Example of a callback body with payment link delivery information
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"invoice sent",
    "date":"2020-01-11T11:50:24+0000",
    "best_before":"2020-10-11T11:50:00+0000",
    "force_payment_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":{ 
    "number":"431422******0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card_holder":"STAPLETON JACK",
    "id":1353,
    "expiry_month":"11",
    "expiry_year":"2022"
  },
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"invoice sent",
    "date":"2020-01-11T11:57:34+0000",
    "created_date":"2020-01-11T11:56:32+0000",
    "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3701",
    "message":"Merchant sent invoice",
    "eci":"02"
  },
  "signature":"hghwGGyapGUQnI+Qg...=="
}

Format of callback with payment cancellation information

Callbacks with payment cancellation information use the standard format for callbacks described in greater details in Callbacks.

The following is the example of a callback with information about cancellation of the 456789 payment; payment status is invoice canceled.

Figure 8. Example of a callback body with payment cancellation information
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"invoice canceled",
    "date":"2020-01-11T11:57:36+0000",
    "best_before":"2020-10-11T11:50:00+0000",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":{ 
    "number":"431422******0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry_month":"11",
    "expiry_year":"2022"
  },
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"invoice canceled",
    "date":"2020-01-11T11:57:34+0000",
    "created_date":"2020-01-11T11:56:32+0000",
    "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3702",
    "message":"Merchant canceled invoice",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}

Format of callback with payment link expiry information

Callbacks with payment link expiry information use standard format for callbacks described in greater details in Callbacks.

The following is the example of a callback with information that the payment link which was previously delivered to email baskerville@mail.uk of the customer stapleton has expired on February 11, 2020 at 11:50.

Figure 9. Example of a callback body with information about payment decline because of payment link expiry
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"expired",
    "date":"2020-01-11T11:57:36+0000",
    "best_before":"2020-02-11T11:50:00+0000",
    "force_payment_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":{ 
    "number":"431422******0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry_month":"11",
    "expiry_year":"2022"
  },
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"expired",
    "date":"2020-01-11T11:57:34+0000",
    "created_date":"2020-01-11T11:56:32+0000",
    "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"3700",
    "message":"Best_before has expired",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}

Format of callback with payment result

Callbacks with payment result information use the standard format for callbacks described in greater details in Callbacks.

The following is an example of a callback with information about a 12.99 GBP payment completion for customer stapleton.

Figure 10. Example of a callback body with information about successful purchase by using payment link
{ 
  "project_id":1901,
  "payment":{ 
    "id":"456789",
    "type":"invoice",
    "status":"success",
    "date":"2020-01-11T11:57:36+0000",
    "best_before":"2020-10-11T11:50:00+0000",
    "force_payment_method":"card",
    "method":"card",
    "email":"baskerville@mail.uk",
    "sum":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "description":"fluorescent paint 400ml"
  },
  "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB&
                  language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%&
                  interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale&
                  signature=hghwGGyapGUQnI+Qg==",
  "account":{ 
    "number":"431422******0056",
    "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654",
    "type":"visa",
    "card_holder":"STAPLETON JACK",
    "id":1353091,
    "expiry_month":"11",
    "expiry_year":"2022"
  },
  "customer":{ 
    "id":"stapleton"
  },
  "operation":{ 
    "id":180001525,
    "type":"invoice",
    "status":"success",
    "date":"2020-01-11T11:57:34+0000",
    "created_date":"2020-01-11T11:56:32+0000",
    "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9",
    "sum_initial":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "sum_converted":{ 
      "amount":1299,
      "currency":"GBP"
    },
    "code":"0",
    "message":"Success",
    "eci":"02"
  },
  "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg=="
}