Creating Payment Requests
Use this guide to learn about how to use our API to generate links to send to your customers
Overview
The atomic unit of Payment Links is a Payment Request. When you create a Payment Request with Skipify via an API call, we send a URL with the response payload where you can view and fulfill the Payment Request. This URL is what you send to your customer using whatever mechanism best fits your business and use case.
When your customer visits the URL of the Payment Request, they will be taken to a dedicated, one-time checkout experience hosted by Skipify. This checkout experience will include all of the line items and charges that you included in your Payment Request API call including subtotals, shipping, taxes, fees, and the order total.
Reminder: Delivery Options
This documentation describes an integration with PayLink that does not include delivery of the link to your end user. With this integration, you will be responsible for link delivery by whatever methods you currently utilize.
If you would like to take advantage of PayLink with text and email delivery, please reach out to your sales representative.
API Request
This endpoint uses HMAC
Please read our API Authentication section to ensure you are crafting your request properly.
To create a payment request, send an API call to:
POST {{baseURL}}/payment-requests
Request Body Parameters
Below is a description of the Request Body for this API call:| Parameter Name | Required? | Type | Description |
|---|---|---|---|
| merchantPaymentRequestId | Yes | string | This is a unique identifier that you set. This identifier will be visible to the customer on the Order Confirmation page so that they can reference their order to you should the need arise. |
| total | No | integer | This is the total amount of the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050.This line item is the amount that we will send to the gateway for payment. To avoid confusion, ensure that the total = (subTotal + tax + shipping) |
| subTotal | Yes | integer | This is the subtotal of the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050 |
| tax | No | integer, nullable | This is the amount of tax for the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050 |
| shipping | No | integer, nullable | This is the amount of shipping for the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050 |
| metadata | No | dictionary, nullable | You can use this parameter to attach key-value data (string, string) to your API call. We do not do anything with this data and simply repeat it back in the API response. The purpose of this parameter is to allow you to store additional, structured information to your Payment Request, such as unique identifiers that you can use internally. We allow for up to 10 keys, with names up to 40 characters and values up to 100 characters Again, Metadata is not used by Skipify in any way, and won't be seen by your customers in our experience. However, be sure to not include any personally identifiable information here! |
| customerEmail | No | string, nullable | This is the customer's email address. We use this field as an identifier for whether or not the customer is registered with Skipify. If they are, they will be able to skip filling out checkout fields and, after a one-time-passcode, can dive directly into payment. |
| expiration | No | dateTime string, nullable | This is an optional parameter you can use to set an expiry on the Payment Request, specified in UTC. Use the format: yyyy-MM-ddTHH:mm:ssZ Ex: 2022-06-02T21:48:02Z |
| lineItems | No | object, nullable | These are the individual items you would like to show the customer as a part of their checkout. There are specific rules about how to set line items. See below for more on the lineItems object. |
Line Items
The lineItems object 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 our experience.
Line Item Parameters
Below is a table describing parameters for each Line Item:| Parameter Name | Required? | Type | Description |
|---|---|---|---|
| sku | Yes | string | This is a top-level product identifier and description of the item. It appears as a header in our Order Summary that your customer will see |
| description | No | string, nullable | This is a sub-header description of the item. It appears under the Order Summary |
| amount | No | integer, nullable | This is the amount of the line item. If null, this will show a dash - this is useful for showing items that have been discounted to zero |
| category | No | string, nullable | This is used to group multiple line items into various categories such as different invoice numbers, different order numbers, etc. |
Line Items are Optional...
...but SKUs are required for each included Line Item!
Line Items don't need to total up
Line Items are for display purposes only, so that customers know what they are purchasing. Because of this, we do not have a rule in place that will total the line items up into your subtotal.
Request Body Example
{
"total":27487,
"merchantPaymentRequestId": "d8a9aa70-08f3",
"subtotal":23700,
"tax":1287,
"shipping":2500,
"metadata": {
"internal_id": "aa1122"
},
"expiration": "2022-06-02T21:48:02Z",
"lineItems": [
{
"sku": "Large Cheese Pizza",
"description": "Some believe that pizza is a vegetable",
"amount": 1500,
"category": "Order 1: Kyle's 3rd Birthday Party"
},
{
"sku": "Birthday Cake",
"description": "Chocolately goodness",
"amount": 2200,
"category": "Order 1: Kyle's 3rd Birthday Party"
},
{
"sku": "Plates and Napkins",
"description":"Free of charge",
"category": "Order 1: Kyle's 3rd Birthday Party"
},
{
"sku": "Case of Craft Beer",
"description": "Tasty",
"amount": 3000,
"category": "Order 2: Parent's Afterparty"
},
{
"sku": "Case of Hard Seltzer",
"amount": 1500,
"category": "Order 2: Parent's Afterparty"
},
{
"sku": "Fee for the Party Clown",
"amount": 15500
}
]
}
API Response
Skipify sends a URL in the response payload where your customers/clients can view and fulfill the Payment Request. You can send this URL to your customer using whatever mechanism best fits your business and use case.
Response Body Parameters
Below is a description of the elements of the response body:| Parameter Name | Type | Description |
|---|---|---|
| url | string (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 tiny-fied, it can be embedded as-is, and can be converted into a QR code. |
| merchantPaymentRequestId | string | This is us playing back to you the request ID you set in the API call. It is displayed to the customer in their Order Summary. |
| paymentRequestId | string (uuid) | This is an internal uuid that we set for your Payment Request. Use this in subsequent API calls, such as modifying a payment request |
| metadata | dictionary | This is us playing back to you the metadata that you set in the API call. This data is not used by us in any way, but can be useful for you to reconcile your orders internally |
Response Body Example
Below is an example of the elements in the response body:{
"url": "https://checkout.gocartpay.com/...",
"merchantPaymentRequestId": "d8a9aa70-08f3",
"paymentRequestId": "77eb2b4b-95ad-4638-831b-02561e67eeaf",
"metadata": {
"internal_id": "aa1122"
}
}
PayLink Example Page
When consumers follow the URL for PayLink, they will see an order summary with a list of the line items of the payment request. Below is an example of what a customer would see when they follow the URL that you send to them:
Line Item Rules and Example
Below are the rules we follow when displaying items in the Order Summary. This is for informational purposes to aid you in crafting your Payment Request:Global Rules
- We display all items within categories 1 - N, with each category bounded by grey bars.
- We display each uncategorized individual item bounded by grey bars.
Rules for Items within a category
- Bound the category collection with grey bars
- Display the category name at the top of the collection of items ("Order 1: Kyle's 3rd Birthday Party')
- Display items in this order:
- Items with a sku, description and amount
- Items with a sku and an amount (but no description)
- Items with a sku and description (but no amount)
- Items with only a sku (no description or amount)
Rules for Items outside of a category
Display each item separately from category groups, bounded by grey bars, in this order:
- Items with a sku, description and amount
- Items with a sku and an amount (but no description)
- Items with a sku and description (but no amount)
- Items with only a sku (no description or amount)
API Reference
Our API Reference contains additional details about this endpoint and its use.
Updated 5 months ago