Fortis Pay docs

Paylinks Endpoint

Paylinks is a way for merchants to create a link that can be used to make a payment. The link can optionally be sent out via email/sms to a customer. Paylinks is similar to Quick Invoices but much simpler.

Paylink Process

The detail listed below in this document explains how to use the API to create and update paylinks. When a paylink is created, the system will optionally send an email and/or SMS with the details of the paylink and a link on how to make a payment towards the invoice. The paylink will only be sent via email or SMS if either of those fields contain valid recipient data.

If an email/SMS is generated by the system during creation time, it will look something like the following:

https://{url}?paylink_id={paylink_id}

If neither the email or SMS fields are populated at creation time, then it is the ISV/Merchants responsibilty to send the paylink to the customer. If the ISV/Merchant chooses to construct and send paylinks on their own, they will need to be constructed like the one listed above. When the user receives this paylink, they will be able to click the link and it will take them to that page that looks like the image below:

Once a payment is made on the paylink, the transaction will show up in the transaction listing with a reference to the paylink.

Endpoint Actions

Create Paylink

POST /v2/paylinks

{
    "paylink":{
        "location_id":"11111111-1111-1111-1111-111111111111",
        "cc_product_transaction_id":"11ec9bbbc02c6176b04f35e7",
        "expire_date":"2022-03-10",
        "amount_due":99999999.99,
        "email":"jones@emailr.com",
        "cell_phone":"1111111111",
        "contact_id":"11ec939cccb05bf494a312a1",
        "delivery_method":3
    }
}
{
    "paylink": {
        "id": "11eca9f78d3654da9f92abd0",
        "cc_product_transaction_id": "11eca9f76a959008955ce03b",
        "ach_product_transaction_id": null,
        "location_id": "11111111-1111-1111-1111-111111111111",
        "paylink_api_id": null,
        "contact_id": "11e999d31a7ab26aa1f36f05",
        "amount_due": "99999999.99",
        "cell_phone": "1111111111",
        "email": "jones@emailr.com",
        "description": null,
        "expire_date": "2022-04-10",
        "status_id": 0,
        "display_product_transaction_receipt_details": 1,
        "display_billing_fields": 1,
        "delivery_method": 1,
        "active": 1,
        "created_ts": 1647964123,
        "modified_ts": 1647964123,
        "created_user_id": "11111111-1111-1111-1111-111111111111",
        "modified_user_id": "11111111-1111-1111-1111-111111111111",
        "_links": {
            "self": {
                "href": "{{url}}/v2/paylinks/11eca9f78d3654da9f92abd0"
            }
        }
    }
}

Update Record

PUT /v2/paylinks/{id} 
NOTE: a Paylink cannot be updated if it's already closed, 

{
	"paylink": {
		"email":"newmail@mailer.com"
	}
}
{
    "paylink": {
        "id": "11eca9f78d3654da9f92abd0",
        "cc_product_transaction_id": "11eca9f76a959008955ce03b",
        "ach_product_transaction_id": null,
        "location_id": "11111111-1111-1111-1111-111111111111",
        "paylink_api_id": null,
        "contact_id": "11e999d31a7ab26aa1f36f05",
        "amount_due": "99999999.99",
        "cell_phone": "1111111111",
        "email": "newmail@mailer.com",
        "description": null,
        "expire_date": "2022-04-10",
        "status_id": 0,
        "display_product_transaction_receipt_details": 1,
        "display_billing_fields": 1,
        "delivery_method": 1,
        "active": 1,
        "created_ts": 1647964123,
        "modified_ts": 1647964123,
        "created_user_id": "11111111-1111-1111-1111-111111111111",
        "modified_user_id": "11111111-1111-1111-1111-111111111111",
        "_links": {
            "self": {
                "href": "{{url}}/v2/paylinks/11eca9f78d3654da9f92abd0"
            }
        }
    }
}

View Single Record

GET /v2/paylinks/{id}

{
    // Empty Payload - Nothing Needed Here
}
{
    "paylink": {
        "id": "11eca9f78d3654da9f92abd0",
        "cc_product_transaction_id": "11eca9f76a959008955ce03b",
        "ach_product_transaction_id": null,
        "location_id": "11111111-1111-1111-1111-111111111111",
        "paylink_api_id": null,
        "contact_id": "11e999d31a7ab26aa1f36f05",
        "amount_due": "99999999.99",
        "cell_phone": "1111111111",
        "email": "jones@emailr.com",
        "description": null,
        "expire_date": "2022-04-10",
        "status_id": 0,
        "display_product_transaction_receipt_details": 1,
        "display_billing_fields": 1,
        "delivery_method": 1,
        "active": 1,
        "created_ts": 1647964123,
        "modified_ts": 1647964123,
        "created_user_id": "11111111-1111-1111-1111-111111111111",
        "modified_user_id": "11111111-1111-1111-1111-111111111111",
        "_links": {
            "self": {
                "href": "{{url}}/v2/paylinks/11eca9f78d3654da9f92abd0"
            }
        }
    }
}

View Record List

GET /v2/paylinks

Note: Filters can be used to search for Paylinks by including the columns you want to filter on as URL parameters. i.e. /v2/paylinks?field=value&field2=value2

{
    // Empty Payload - Nothing Needed Here
}
{
    "paylinks": [
        {
            "id": "11eca9f78d3654da9f92abd0",
            "cc_product_transaction_id": "11eca9f76a959008955ce03b",
            "ach_product_transaction_id": null,
            "location_id": "11111111-1111-1111-1111-111111111111",
            "paylink_api_id": null,
            "contact_id": "11e999d31a7ab26aa1f36f05",
            "amount_due": "99999999.99",
            "cell_phone": "1111111111",
            "email": "ezekiel@zeamster.com",
            "description": null,
            "expire_date": "2022-04-10",
            "status_id": 0,
            "display_product_transaction_receipt_details": 1,
            "display_billing_fields": 1,
            "delivery_method": 1,
            "active": 1,
            "created_ts": 1647964123,
            "modified_ts": 1647964123,
            "created_user_id": "11111111-1111-1111-1111-111111111111",
            "modified_user_id": "11111111-1111-1111-1111-111111111111",
            "_links": {
                "self": {
                    "href": "{{url}}/v2/paylinks/11eca9f78d3654da9f92abd0"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "links": {
                "self": {
                    "href": "{{url}}/v2/paylinks?page_size=1&page=1"
                },
                "next": {
                    "href": "{{url}}/v2/paylinks?page_size=1&page=2"
                },
                "last": {
                    "href": "{{url}}/v2/paylinks?page_size=1&page=2"
                }
            },
            "totalCount": 2,
            "pageCount": 2,
            "currentPage": 0,
            "perPage": 1
        },
        "sort": {
            "attributes": {
                "created_ts": "desc"
            }
        }
    }
}

Delete Record

DELETE /v2/paylinks/{id}

{
    // Empty Payload - Nothing Needed Here
}
No JSON Response.  HTTP Response Code Only.

204 - Success, Paylink was deleted.
404 - Fail, Paylink not found.

Resend Notification Email / SMS Notification

There may be times when it is necessary to Resend the Notification Email and/or SMS Notification to the recipient.  You can use the following request to make that happen.

POST /v2/paylinks/{id}/resend ​​​

{
    // Empty Payload - Nothing Needed Here
}
No JSON Response.  HTTP Response Code Only.

204 - Success, Paylink Notification email was sent.
404 - Fail, Paylink not found.
No JSON Response.  HTTP Response Code Only.

204 - Success, Paylink Notification email was sent.
404 - Fail, Paylink not found.

 

Fields

Name Min Max Format POST Required POST Allowed PUT Allowed Comments
ach_product_transaction_id 24 36 string ✔ ✔ ✔ ACH product transaction on which Paylink is created. This field is optional and will default to default_ach product if not supplied at all. Either this or cc_product_transaction_id must be supplied. Changes are allowed on PUT if payments have not been made against Paylink.
active 1 1 boolean       Determines whether the invoice is currently active or not
amount_due 0 12 decimal(10,2) ✔ ✔   This is the amount that need to be paid (automatically calculated by system). amount_due= sum of items in item_list
cc_product_transaction_id 24 36 string ✔ ✔ ✔ CC product transaction on which Paylink is created. This field is optional and will default to default_cc product if not supplied at all. Either this or ach_product_transaction_id must be supplied. Changes are allowed on PUT if payments have not been made against Paylink.
cell_phone 1 10 string   ✔ ✔
required if delivery_methodis set to 2[SMS], 3[Both email and sms], this will be the recipient of the SMS
contact_id 24 36 string   ✔ ✔ Optional, the contact of the paylink
contact_api_id 1 64 string   ✔ ✔ Optional. If there is a matching contact in the system, the API will translate this to a contact.id value and save it with the Paylink.  
The contact_id will be returned in the response instead of  contact_api_id.
created_ts 10 10 timestamp       System created timestamp
created_user_id 24 36 string       User id who created the Paylink
delivery_method 1 1 int ✔ ✔ ✔

the method of notifying the recipient

0 - none
1 - Email
2 - SMS
3 - Both

display_product_transaction_receipt_details

 1 1 boolean       show the receipt details after the successful payment

display_billing_fields

 1 1 boolean       show the billing field inputs in the paylink form
email 5 128 string   ✔ ✔ Optional. An email address that should be used as the "To" address when sending a Paylink Notification email.
expire_date 10 10 date   ✔ ✔ Expire date of paylink
id 24 36 string       System generated id
location_id 24 36 string ✔ ✔   Location id to which Paylink belongs to
modified_ts 10 10 timestamp       System created timestamp
modified_user_id 24 36 integer       User id who modified the paylink
paylink_action   10 string   ✔ ✔ the action that will be used by the form when making the payment
possible values:
sale
auth-only
paylink_api_id 0 64 string   ✔ ✔ An alterate id that can be used to access the record. API id's are unique per location.
status_id 1 1 integer     ✔

The various statuses of the paylink:

0 - Unpaid

1- Paid

 

Expands (Related Records)

For detail on how to use Expands on an Endpoint, please visit the Expands (Related Records) page.

Related Record Filter Name
Contact contact
Email Blacklist email_blacklist
SMS Blacklist sms_blacklist
Location location
Tags tags
User created_user
The url of the actual payment form payment_url

 

An example of “expanding” this endpoint to one of the above related records would look like this:

GET /v2/paylinks/xxxxxxxxxxxxxxxxxxxxxxxx?expand=contact

To use multiple expands on this endpoint, simply include them both separated by a comma like so:

GET /v2/paylinks/xxxxxxxxxxxxxxxxxxxxxxxx?expand=created_user,contact,payment_url