Creating PayLinks

Learn how to use our API to generate PayLinks to send to your customers

Overview

Creating a PayLink starts with you providing customer and order details to Skipify via a POST to create a PayLink. You can then use the Sending PayLinkscall to have Skipify send the Pay Link via email or SMS to the Shopper. Alternatively, Skipify provides in the response payload a URL that you can send to your customer using whatever mechanism you may already have in place.

When the Shopper visits the PayLink URL, they will be taken to a dedicated, one-time checkout experience hosted by Skipify. This checkout experience will include the line items and charges that you passed in your Payment Request API call including subtotals, shipping, taxes, and order total.

📘

Reminder: Delivery Options

If you want to take advantage of PayLinks with text and email delivery, you will need to set sendEmail or sendSms to true when creating a PayLink. The Send PayLinks endpoint will be used to send the link via email and/or SMS.

API Request

👍

This endpoint uses HMAC

Check out our API Authentication section to learn more

To create a payment request, send an API call to:

Staging:POST https://stage-paylinks.skipify.com

Production:POST https://paylinks.skipify.com

Request Body Parameters

Parameter NameRequired?TypeDescription
merchantIdyesstringA unique identifier that Skipify assigns to the merchant and is the account that the Paylink will be created for.
merchantInvoiceIdnostringA unique identifier that’s applicable to your systems. This identifier will not be visible to the customer. It can be used for your reference to link a Skipify order to a record in your systems. Max 255 char.
customernoobject, nullableThe customer object includes a set of properties that allows us to prefill the checkout experience and skip a couple steps. We’ll use information passed as an identifier to determine if the customer is registered with Skipify.
memonostringA generic field to allow you to add more information on the specific usage of this PayLink. This will be displayed to the customer.
descriptionnostringA generic field to allow you to add more information on the specific usage of this PayLink. This will be displayed to the customer.
currencyCodeyesstring3 letter code to identify the currency. Skipify is only processing transactions in USD at this time.

Make sure you are passing USD as a value
sendEmailyesbooleanThis field is used if you are planning on using Skipify to deliver the link to the customer via email. If set to true, the email in the customer block is required.
sendSmsyesbooleanThis field is used if you are planning on using Skipify to deliver the link to the customer via text. If set to true, the phone in the customer block is required.
customerConsentconditionalbooleanThis field must be set to True if either sendEmail or sendSms is True. The flag is to ensure that the customer consented to receive the link.
shippingnointeger, nullableThis is the amount of shipping for the PayLink. The last two digits are cents, so $20.50 would be sent as 2050.
taxnointeger, nullableThis is the amount of tax for the PayLink. The last two digits are cents, so $20.50 would be sent as 2050.
lineItemsyesarrayThese are the individual items you would like to show the customer as a part of their checkout. You may pass a max of 50 items in a single request.
expirationnodateTime, string, nullableThis is an optional parameter you can use to set an expiry on the PayLink, specified in UTC.

Use the format:
yyyy-MM-ddTHH:mm:ss.SSSZ

Ex:
2022-06-02T21:48:02Z
metadatanoObject, nullableYou can use this parameter to attach key-value data (string, string) to your API call. The purpose of this parameter is to allow you to store additional, structured information to your PayLink.

We allow for up to 10 keys, with names up to 40 characters and values up to 100 characters

Be sure to not include any personally identifiable information here!

String, boolean, or number allowed as values.

Line Items

The lineItems array allows a customer to see a list of items included in the Payment Request. This list can be viewed in the Order Summary portion of the Skipify experience.

Line Item Parameters

Parameter NameRequired?TypeDescription
skuyesstringThe product identifier of the item. It appears as a header in our Order Summary that your customers will be able to see. This can be leveraged for other use-case as well. For example: invoice or bill number. Max 255 char.
quantitynointegerThe quantity of the item being sold. If null, this is defaulted to 1.
price*yesintegerThe price of the item. The last two digits are cents, so $20.50 would be sent as 2050.
*If you want to add a Discount to a PayLink, pass a negative 'price' ie. '-250' and an appropriate 'description'
descriptionnostringThe description of the item being sold. This will be displayed to the customer.
Examples: Anchovy Pizza, New Balance 650, etc. Max 255 char.
categorynostringThe category of the product or service being sold
metadatanoObject, nullableYou can use this parameter to attach key-value data (string, string) to your API call. The purpose of this parameter is to allow you to store additional, structured information to your PayLink.

We allow for up to 10 keys, with names up to 40 characters and values up to 100 characters

Be sure to not include any personally identifiable information here!

String, boolean, or number allowed as values.

📘

Note

Line items will be used to calculate the subtotal

Customer

Customer Parameters

Parameter NameRequired?TypeDescription
emailconditionalstringThe customer email will be used to search the user in our systems. If recognized, their saved payment methods will be surfaced within the PayLink checkout experience.
phoneconditionalstringThe customer phone number will be used to pre-populate the checkout experience if a phone number is not available in our systems.
firstNamenostringThe customer's first name
lastNamenostringThe customer's last name
customerIdnoUUIDThe customer's unique identifier. When provided, no other fields can be included in the customer object

Request Body Example

{
  "merchantInvoiceId": "string",
  "customer": {
    "email": "[email protected]",
    "phone": "4140892098",
    "firstName": "string",
    "lastName": "string",
    "accountName": "string",
    "customerId": "string"
  },
  "customerConsent":true,
  "memo": "string",
  "description": "string",
  "currencyCode": "string",
  "sendEmail": true,
  "sendSms": true,
  "shipping": 0,
  "tax": 0,
  "lineItems": [
    {
      "sku": "string",
      "quantity": 1,
      "price": 1,
      "description": "string",
      "category": "string",
      "metadata": {
        "additionalProp1": {}
      }
    }
  ],
  "expiration": "2028-08-10T21:38:00.784Z",
  "metadata": {
    "additionalProp1": {}
  }
}

API Response

Skipify sends a URL in the response payload where your customers/clients can view and fulfill the PayLink request. You can send this URL to your customer using whatever mechanism best fits your business and use case. The response will include all values populated in the request with the following additional fields:

Parameter NameTypeDescription
paylinkIdstringSkipify’s unique identifier for the PayLink. This ID will be needed to use the other endpoints.
linkstring (url)What we all came here for! This is the URL that you will use to forward to your customers.

Do what you like with this URL, it can be embedded as-is, and can be converted into a QR code.
shortLinkstring (url)A Skipify generated Short Link that you can use instead of the link to forward to your customers if you deliver the PayLink yourself.
merchantInvoiceIdstringA unique identifier that you send with the request is returned in the response. This identifier will not be visible to the customer. It can be used for your reference to link a Skipify order to a record in your systems. Max 255 char.
currencyCodestringUSD only today
merchantIdstringThe merchantId that this Paylink was created for
metadataobjectIf sent in the request, will be returned in the response
descriptionstringThe description sent with the Paylink create request. This will be displayed to the customer.
memostringThe memo sent with the Paylink create request. This will be displayed to the customer.
orderIdstringwill be Null upon Paylink Creation. OrderId is assigned to Paylink once Payment completed.
expirationdateTime, string,The expiration date/time of the Paylink that was set in the Request.
Ex:
2024-06-02T21:48:02Z
sendSMSbooleanThe boolean flag set on the request.
sendEmailbooleanThe boolean flag set on the request.
createdAtdateTime, stringThe date/time the Paylink was created at in UTC
updatedAtdateTime, stringThe date/time the Paylink was updated in UTC
customerConsentbooleanThe boolean flag set in the request, must be true to send
taxintegerAmount of tax sent for the Paylink
shippingintegerAmount of shipping sent for the Paylink
subTotalintegerTotal price of lineItems and lineItems tax
totalintegerTotal price of lineItems, lineItems tax, shipping, tax
orderTotalintegerThe total plus any fees applied during payment
amountPaidintegerThe amount that was paid by the customer
lastSentAtdateTime, stringThe last time the Paylink was sent to the customer
lineItemsarrayThese are the line items sent with the request. This object also returns:
'createdAt' - dateTime, string
'updatedAt' - dateTime, string
deliveryLogsarrayList of SMS and/or email delivery attempts
openOrdersarrayList of orders that have been created for the Paylink
eventsarrayList of events associated with this Paylink, upon creation, eventType= CREATED
statusstringcurrent status of Paylink, upon created status = CREATED
customerobjectCustomer object sent with request
attachmentsarrayList of attachments file names if added to Paylink

Example

{
    "paylinkId": "string",
    "link": "string",
    "shortLink": "string",
    "merchantInvoiceId": "string",
    "currencyCode": "USD",
    "merchantId": "string",
    "metadata": null,
    "description": "string",
    "memo": "string",
    "orderId": null,
    "expiration": "2025-02-28T16:13:00.000Z",
    "sendSms": true,
    "sendEmail": true,
    "createdAt": "2024-04-19T16:22:00.599Z",
    "updatedAt": "2024-04-19T16:22:00.599Z",
    "customerConsent": true,
    "tax": null,
    "shipping": null,
    "subTotal": 1010,
    "total": 1010,
    "orderTotal": null,
    "amountPaid": null,
    "lastSentAt": null,
    "lineItems": [
        {
            "paylinkItemId": "string",
            "sku": "123987ABCXYZ",
            "paylinkId": "string",
            "price": 1010,
            "quantity": 1,
            "tax": 0,
            "description": "Widget",
            "category": "Items",
            "metadata": null,
            "createdAt": "2024-04-19T16:22:00.599Z",
            "updatedAt": "2024-04-19T16:22:00.599Z"
        }
    ],
    "deliveryLogs": [],
    "openOrders": [],
    "events": [
        {
            "eventId": "string",
            "paylinkId": "string",
            "eventType": "CREATED",
            "oldValue": null,
            "newValue": null,
            "createdBy": "API Key",
            "createdAt": "2024-04-19T16:22:00.599Z"
        }
    ],
    "status": "CREATED",
    "customer": {
        "accountName": null,
        "email": "[email protected]",
        "phone": "3333333333",
        "firstName": "first",
        "lastName": "last",
        "paylinkCustomerId": null
    },
    "attachments": []
}

Skipify baner with link to contact us form