Hosted Payment Links

What are Hosted Payment Links?

Hosted Payment Links are uniquely generated payment links which allow customers to pay when and how they choose. Each payment link is generated with a unique identifier for an associated order. Hosted Payment Links are entirely hosted by PaySimple, taking the development work out of hosting your own payment links for customers.

Hosted Payment Links can be generated and distributed by your code in any way. If you have an SMS or email service, Hosted Payment Links can be distributed to customers via SMS, QR code, or email - allowing them to pay on the spot in a mobile-responsive web page, or at their earliest convenience after reviewing an invoice.

Credit Card and ACH (echeck) are both supported with Hosted Payment Links.

Use Cases

Hosted Payment Links are a great option for merchants with single-use transactions. Home services will be able to make great use of Hosted Payment Links by delivering links via email or SMS. A quick SMS message to the customer with a link to pay can allow for quicker payment experience without requiring additional swiper hardware.

How does this compare to a Payment Form?
Payment Forms are for individual catalog items and multiple transactions. Hosted Payment Links are more customizable and flexible for items, but are designed for a single-use transaction.

How to use Hosted Payment links

Authorization for Hosted Payment Links will use Basic Merchant Auth. This information can be found within our API 5.0 "Authorization" section.

Hosted Payment Links are simple and intuitive to use. At this time, the primary endpoint is "Create Hosted Payment Link". This will be the endpoint which initializes the transaction and returns the URL for you to distribute to your customers.

For a video demo, please contact [email protected]

Hosted Payment Link Endpoints

Below is an example of a Create Hosted Payment Link call. In addition, you can Delete Hosted Payment Links by switching the tab within the window below.

POST /ps/payment_link
{
	"external_id": "123456789",
	"external_id_label": "order #:",
	"item":
	{
		"price": 1234,
		"allow_price_entry": false, 
		"name": "name of of the item",
		"description": "long description of the item", 
		"tax_amount": 4.56
	},	
	"customer":
	{
		"first_name": "first", 
		"last_name": "last",
		"email": "[email protected]" 
	},
	"checkout_config":
	{
		"company":
		{
			"name": "Company",
			"email": "[email protected]",
			"phone": "7202223333",
			"website": "test.com",
			"address":
			{
				"line1": "123 78th st",
				"line2": "ste 89",
				"city":  "Denver",
				"state": "CO",
				"postal_code": "80202"
			}
		},     
		"payment_acceptance": ["credit_card", "bank_account"],
		"header_background_color": "000000",
		"header_text_color": "ffffff",
		"show_company_email": true,
		"show_company_phone": true,
		"show_company_address": true,
		"show_external_id": true
	}
}
//Delete Hosted Payment Link
{
  {{api5}}/ps/payment_link/"63fd3d306a3c42c0c5fbe189"
}

Response:

200 OK
{
  "data": {
  	"id": "63fd3d306a3c42c0c5fbe189".
    "payment_link": "https://my_subdomain.mypaysimple.com/s/pay/DZDcP3DaCp0sOJDZD39ZC6CrPc9bCJWv"
  }
}
200 OK
{
 //Delete Hosted Payment Link - Response
}

Request Properties

PropertyTypeDescription
external_idstringOptional. A merchant defined identifier that will appear during checkout and in reports. Max length 50 characters.
external_id_labelstringOptional. Text that will be used as a label for the passed in external_id. Max length 50 characters.
itemobjectRequired. Item that will be checked out by the customer. (see Item Properties)
customerobjectOptional. Used to auto populate the customer fields during checkout. (see Customer Properties)
checkout_configobjectOptional. Used to configure checkout parameters, such as colors and design settings. (see Checkout Configuration Properties)

Item Properties

PropertyTypeDescription
pricedecimalOptional, but required if allow_price_entry is false. Pre-tax amount that should be charged for the item. Max 2000000.
allow_price_entrybooleanOptional, must be true if price is not defined. Whether or not the customer can edit the price at checkout. Default false.
namestringRequired. Name of the item being purchased. Length 2-50 characters.
descriptionstringOptional. Description of the item being purchased. Max length 500 characters.
tax_amountdecimalOptional. Amount of tax to charge, as a percentage of price. The total amount charged at the time of checkout is the sum of price and the calculated tax amount. Max 20.

Customer Properties

PropertyTypeDescription
first_namestringOptional. Used to populate the customer first name field during checkout. Max length 150 characters.
last_namestringOptional. Used to populate the customer last name field during checkout. Max length 150 characters.
emailstringOptional. Used to populate the customer email address field during checkout. Max length 100 characters, must be in a valid email format.

Checkout Configuration Properties

PropertyTypeDescription
payment_acceptancearrayOptional. Payment types that will be allowed at checkout. Valid values: credit_card, bank_account. Default credit_card and bank_account.
header_background_colorstringOptional. Hexadecimal color to use for the header background. Length 6 characters. Default 000000.
header_text_colorstringOptional. Hexadecimal color to use for text that appears in the header. Length 6 characters. Default ffffff.
show_company_emailbooleanOptional. Whether to show the company email in the page footer. Default true.
show_company_phonebooleanOptional. Whether to show the company phone in the page footer. Default true.
show_company_addressbooleanOptional. Whether to show the company address in the page footer. Default true.
show_external_idbooleanOptional. Whether to show the external_id and external_id_label at checkout. Default true.
companyobjectOptional. Company information that will be displayed at checkout. If empty, all properties will default to the current merchant settings (see Company Properties)

Company Properties

PropertyTypeDescription
namestringOptional. Name of the company that will appear throughout checkout. Max length 300 characters.
emailstringOptional. Email address of the company that will appear throughout checkout. Max length 100 characters, valid email address format.
phonestringOptional. Phone number of the company that will appear throughout checkout. Max length 10 characters, all digits.
websitestringOptional. Website of the company that will appear throughout checkout. Max length 2000 characters, valid URL format.
address.line1stringOptional. Line 1 of the physical address of the company that will appear throughout checkout. Max length 100 characters.
address.line2stringOptional. Line 2 of the physical address of the company that will appear throughout checkout. Max length 50 characters.
address.citystringOptional. City of the physical address of the company that will appear throughout checkout. Max length 100 characters.
address.statestringOptional. State of the physical address of the company that will appear throughout checkout. Max length 2 characters.
address.postal_codestringOptional. Postal code of the physical address of the company that will appear throughout checkout. Max length 20 characters.

Response Properties

PropertyTypeDescription
idstringUnique hosted payment link identifier.
payment_linkstringA shareable URL of the newly created hosted payment link.

After the payment

Upon checkout completion, the following will occur:

  1. An email receipt will be sent to your customer's email address.
  2. Webhooks you are subscribed to will be fired and become available for your integrated product.
  3. New transactions will be created in the PaySimple product reports. Transaction reports will include your provided ExternalId values.

Sample Screenshots

Header color and Header text colors are customizable. The following is a demonstration of the customer experience, which is mobile-responsive.

Pre-Checkout

Pre-Checkout

Checkout

Checkout

Checkout Complete

Checkout Complete

Frequently Asked Questions

Q: How are taxes included?
A: Tax information is taken in as a percentage as part of the request. It is calculated and added to the total amount due at checkout.

Q: How long do Hosted Payment Links last?
A: Hosted Payment Links do not expire. They will remain valid until a payment is completed OR the "Delete Payment Link" endpoint is called to delete the endpoint. The delete endpoint can be found in the Endpoints section above, within the second window tab.

Q: Can I use multiple Hosted Payment Links for a single transaction?
A: No, only one transaction should be made per hosted payment link.

Q: Are links mobile-responsive?
A: Yes! Customers can pay via mobile devices, tablets, and desktop computers.

πŸ“˜

Still have technical questions?

Integrated partners can submit support tickets directly to the PaySimple team at [email protected].