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 initial request to generate a web address that allows customers to make purchase that involves a one-time transfer of funds from a customer to a merchant with or without authorization hold. The ecommpay payment platform supports two versions of payment link purchase:

  • one-step payment link purchase
  • two-step payment link purchase

Both versions can be used for registering a COF purchase and utilise Payment Page. The payment link to this payment form is delivered to the customer by the ecommpay payment platform through email or by the merchant using any available delivery media.

The merchant chooses the payment link validity period and the payment version 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 after the customer opens the payment link.

Because payment link purchases are processed by using Payment Page, payment requests may contain either a card token or no information about payment instrument. In the latter case, the customer is required only to provide evidence of payment instrument validity; 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 3‑D Secure authentication, provision of additional payment information, or currency conversion. These procedures are performed by Payment Page and require no additional effort on merchant's web service side.

Processing scenarios

Suppose that your customer wants to make a 12.99 GBP purchase by using payment link and asks you to send the payment link to email baskerville@mail.uk.

Successful purchase

  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.
    Figure 1. Sample email with a payment link


  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.
    Figure 2. Sample page for purchase with card


  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.
    Figure 3. Sample payment result page


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 4. Sample payment cancellation email


  3. Customer clicks the payment link and is presented with the payment cancellation page.
    Figure 5. Sample 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 6. 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, email that is sent to customer includes the following information from the request for payment link:

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


Merchant can customise the template that is used for payment link email . The customisation can include but is not limited to changing the parameters included in emails and customising email design and layout.

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

Payment form design

By default, the payment form displayed to the customer has the standard design variant 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 the key 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 8. 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 9. 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 10. 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 11. 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 12. 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=="
}