Skip to main content

Payment Links

Creating Payment Links Using the API

The payment links API allows you to integrate AndDone payment link functionality into your existing website or application.

The payment links API allows you to integrate AndDone payment link functionality into your existing website or application. You can create a Payment Link using the AndDone API by calling the POST Create Payment Link method. To create a Payment Link, the PaymentLink feature must be enabled for the merchant in the AndDone Admin Portal.

Setting the Request Parameters

This section describes how to set the body parameters for the POST Create Payment Link method.

Merchant Reference (title)

The Merchant Reference is a unique ID assigned to the payment by the merchant. Set the merchant reference number in the title parameter.

“title”: “PL10460327350978”,

Note: The title parameter is required and must be unique per merchant in order to generate a payment link.

Merchant ID

Set the merchantID parameter to your unique Merchant ID, also known as env_merchantId or x-app-key.

Note: The env_merchantID parameter is also passed in the API path.

Reference ID

A reference ID associates the payment link with IPFS Account Number, an IPFS Quote ID, an insurance policy number, a payment invoice number or any other unique payment ID assigned by the merchant.

In API version 2.1, each payment link is associated with a single unique payment reference ID.

In API version 2.2, multiple reference IDs can be associated with a payment link.

Set the referenceType to indicate the type of reference ID associated with the payment:

Value Description
1 Quote ID - The IPFS quote ID number associated with the payment. This reference type flags the transaction as a IPFS down payment.
2 Account Number - The IPFS account number associated with the payment. This reference number flags the transaction as an IPFS installment payment.
3 Policy Number - The unique insurance policy ID.
4 Invoice Number - The unique agent-assigned invoice number associated with the payment.
5 Other - This can be any other merchant-assigned reference number or string that is used to identify the payment.

Set the referenceNumber parameter to the reference ID value.

If the referenceType is 5 (Other), use the referenceKey parameter to provide a descriptive tag for the referenceNumber.

Example: API version 2.1 - single reference ID

"referenceType": "2",
"referenceNumber": "7523776",

Example: API version 2.2 - multiple reference IDs
In API version 2.2 reference IDs are passed IDs in the referenceDataList array. You can pass one or multiple reference IDs.

    "referenceDataList": [
        {
            "referenceType": "2",
            "referenceNumber": "86753023413"
        },
        {
            "referenceType": "5",
            "referenceNumber": "CST-54327890321",
            "referenceKey": "Customer Number"

        }
    ],

Accepted Payment Types

Set the PaymentTypes parameter to indicate the methods of payment that the customer can use in the payment link. You must specify at least one payment type for the payment link to be valid.

"intent": { 	
	"PaymentTypes": [		
		"ACH",		
		"CreditCard",		
		"DebitCard"
        ]
    }

Payment Amount

Set the amount parameter to indicate the total payment amount in U.S. dollars.

    "amount": "125.75",

Payment Description

Set the paymentDescription to indicate the purpose of the payment.

"paymentDescription": "Commercial Property Insurance premium installment.",

Each payment link is required to have a defined expiration period after which the link is no longer valid and cannot be accessed by the customer. The expiration time unit (minutes, hours, days, or weeks) is set in the expireInUnit parameter.

  • 1 - minutes
  • 2 - hours
  • 3 - days
  • 4 - weeks

The expiration period is set in the expireIn parameter. In the following example, the payment link is set to expire in 7 days.

    "expireIn": "7",
    "expireInUnit": 3,

Customer Details

The additionalDetailsPreference parameter is used to specify the customer information that is collected or displayed in the payment form. There are three options:

Value Description
1 The merchant specifies one or more of the following to be entered by the customer: First Name, Last Name, Email, Phone number.
2 The customer’s First Name, Last Name, Phone Number, and/or Email are populated by the merchant in the customers object. This information can be edited by the customer before submitting the payment.
3 No customer contact information is displayed or collected in the form. Only merchant and payment information is displayed.
4 (version 2.2 and later) The customer’s First Name, Last Name, Phone Number, and/or Email are populated by the merchant in the customers object. This information cannot be edited by the customer.

The selectedCustomerFields parameter is required with additionalDetailsPreference option 1.

Example: Customer fills in details

In the following example, the customer is required to enter their First Name, Last Name, and Email address. 

"additionalDetailsPreference": 1,
"selectedCustomerFields": "First Name,Last Name,Email",

Example: Merchant provides details

In the following example, the customer information is provided by the merchant. The customers object, required with this option, is passed containing the customer’s First Name, Last Name, Phone Number, and/or Email as they will be displayed in the payment form. 

"additionalDetailsPreference": 2,
"customers": [
	{
	"firstName": "Jane",
	"lastName": "Doe",
	"email": "[email protected]",
	"phone": "+18765551616",
	}
]

Confirmation Page

You can set the confirmation page that is displayed to the customer after submitting a payment using the responseType parameter.

Value Description
1 Custom Message or Redirect - This option allows you to display a custom message (callbackMessage) in the payment confirmation page and/or to redirect the customer to a specified URL (callbackApiUrl) after payment confirmation.
2 Default - The payment confirmation page displays the default message set in the Branding page of the AndDone Merchant Portal.

When specifying a callbackApiUrl you have the option of setting a delay in seconds before the customer is redirected to the URL. The redirect delay can be set in the redirectionTime parameter. The default redirect delay is 15 seconds.

Example: Default Agent Message

In this example, the default payment confirmation page is displayed as defined in the Branding page of the AndDone Merchant Portal.

"responseType": 0,
"callbackParameters": {
	"callbackApiUrl": "",
	"callbackMessage": ""
}

Example: Custom Agent Message

In this example, the default message in the payment confirmation page is replaced by the specified custom callbackMessage.

"responseType": 1,
"callbackParameters": {
	"callbackApiUrl": "",
	"callbackMessage": "Thank you for your payment!"
}

Example: Redirect to website

In this example, the customer is redirected to the callbackApiUrl 20 seconds after the default payment confirmation page is displayed. 

"responseType": 1,
"callbackParameters": {
	"callbackApiUrl": "https://www.payconfirmationpage.com",
	"callbackMessage": ""
	"redirectionTime": "20"
}

The paymentLink URL is returned in the POST Create Payment Link response. This URL can be shared with customers through Email, SMS, or social media. When a customer opens a payment link, they are directed to a secure, AndDone-hosted payment page.

You can use the PUT Update Payment Link Details method to modify the details of an existing payment link.