Overview

A Payment Intent is a representation of an intent to submit a Payment.

What Is a Payment Intent?

A Payment Intent serves as an instrument to track a Payment from inception to submission and helps confirm that a customer's expectations are accurately captured, reflected, and communicated as more Payment details are collected.

Payment Intents are typically referred to in this guide as drafted Payments or staged Payments, highlighting the customer intent and partial completeness as core characteristics defining the asset.

Advantages of Using Payment Intents

Some of the advantages of using Plastiq Connect's Payment Intents to enhance your customer experience include:

  • Payment fees - a customer can know the anticipated total charge of their card or bank account ahead of submission
  • Payment delivery date - a customer can know when a Payment is expected to be delivered
  • Payment feasibility - a customer can know if a Payment can be fulfilled via Plastiq Connect

A Two-Step Process

Payments via Plastiq Connect are typically made in a two-step process.

Step One

Partners first create a Payment Intent with as much information as they have about a given payment.

This includes information about the Payer, the Recipient, the Recipient Category, the Payment amount and currency, the Payment Method, and other Documents.

Step Two

Plastiq responds with a detailed Payment Intent object describing all of the details of the payment including the available delivery timelines, source descriptor, applied fees, and target descriptor.

This Payment Intent object can then be used to create a Payment.

Payment Intent Attributes

AttributeDescriptionAPI Field Name
Source AmountThe Payment dollar amount that will be withdrawn from the Payment MethodsourceAmount
Target AmountThe Payment dollar amount that will be disbursed to the RecipienttargetAmount
PayerThe individual or business making the PaymentpaymentIntent.id
Payment MethodThe financial instrument used to fund the PaymentpaymentMethod.id
RecipientThe individual or business receiving the Paymentrecipient.id
Remittance DetailsThe Payment details that are sent alongside a Payment to help the Recipient reconcile the Payment

For example, an invoice number or account holder name

Note: If an accountName is not provided, it will default to the contact firstName + lastName or the businessName of the Payer.
details
FeesThe fees applied on the Paymentfees
Delivery DateThe date on which the Payment delivery can be fulfilled bydeliveryDate
StatusThe status of the drafted Paymentstatus
Is ExpeditedA flag indicating whether the payment should be expedited

Note: if true, the fastest available delivery date will be automatically chosen
isExpedited
Delivery OptionsThe list of available delivery dates with their corresponding fees and when the date is valid untildeliveryOptions

Status

Payers who attempt to create a Payment Intent for the first time may not have the full set of information needed to successfully submit a Payment.

However, a Payer can still create a Payment Intent with incomplete details and address them later on.

This feedback is provided via the status and statusReasons properties of the Payment Intent response. Here is an example of a Payment Intent response payload that was returned with a complete set of details:

{
    "id": "0498fc89-d391-478c-863a-fc4c2198300a",
    "fees": [
        {
            "amount": {
                "value": 2.9,
                "currency": "USD"
            },
            "type": "PLASTIQ_SERVICE_FEE",
            "rate": "2.90%"
        }
    ],
    "sourceAmount": {
        "currency": "USD",
        "value": 102.9
    },
    "targetAmount": {
        "currency": "USD",
        "value": 100
    },
    "paymentMethod": {
        "id": "9923ff81-8f49-480b-8c45-1b99796d69a0"
    },
    "recipient": {
        "id": "5238d74f-3faa-499f-b26b-4c5e706af064"
    },
    "payer": {
        "id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
    },
    "details": {
        "accountName": null,
        "accountNumber": null,
        "memo": null
    },
    "status": "CAPTURABLE",
    "statusReasons": [],
    "deliveryDate": "2021-05-13",
    "createdAt": "2021-05-11T10:52:39.000Z",
    "expiresAt": "2021-05-11T23:59:59.000Z",
    "deliveryOptions": [
        {
            "cutoffTime": "2021-05-11T14:59:59.000Z",
            "deliveryDate": "2021-05-11",
            "fees": [
                {
                    "amount": {
                        "value": 2.9,
                        "currency": "USD"
                    },
                    "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T21:59:59.000Z",
            "deliveryDate": "2021-05-12",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T23:59:59.000Z",
            "deliveryDate": "2021-05-13",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        }
    ]
}

Expiration

You'll notice that status returns CAPTURABLE and statusReasons returns an empty array.

As long as the Payment Intent is used to create a Payment before the expiresAt date, the Payment will be CAPTURED.

This time expiration window is designed to guarantee that the Payment can be delivered by the quoted deliveryDate.

Delivery Date

Delivery dates will vary based on the following set of determining factors:

  1. Time of creation
  2. Recipient's receiving method (ACH, Check, Wire, or EFT),
  3. Day of the week
  4. US & Canada bank holidays

Expiration Dates and Delivery Dates

Pay attention to the expiresAt date, a validation error will be returned if the Payment Intent is modified or used to create a Payment after that date. Fetching an expired Payment Intent, its status will show as EXPIRED.

Expedited Payments

Connect offers expedited payments for all recipients when submitted before their expiration. This option reduces SLAs but will incur additional delivery fees.

For example:

Expedited Check (overnight)
Description Payment sent via FedEx Priority Overnight.

FedEx Priority Overnight does not deliver to P.O. Boxes or non-US addresses.
Delivery Timeframe1 business day
Expedited Delivery Pricing2.90% (Plastiq Fee)

+ 0.5% (Expedited Processing Fee)

+ $29.00 (Expedited Handling Fee)

+ $1.49 (Delivery Fee)
Expedited Check (2 days)
Description Payment sent via FedEx Priority Overnight.

FedEx Priority Overnight does not deliver to P.O. Boxes or non-US addresses.
Delivery Timeframe2 business days
Expedited Delivery Pricing2.90% (Plastiq Fee)

+ 0.2% (Expedited Processing Fee)

+ $29.00 (Expedited Handling Fee)

+ $1.49 (Delivery Fee)

Payment Intent Flexibility

By default, the delivery date of the payment will automatically be chosen. This date corresponds with the SLA for a standard delivery unless isExpedited is true, in which case, it would be an expedited delivery.

Now let's consider a scenario where a Payer wants to choose the delivery date instead. The Payment Intent endpoint exposes what delivery options are available. You can then update the Payment Intent with the chosen delivery date.

Using the above scenario, here are examples of the Payment Intent requests and responses.

{
  "targetAmount": {
    "value": 100,
    "currency": "USD"
  },
  "paymentMethod": {
    "id": "9923ff81-8f49-480b-8c45-1b99796d69a0"
  },
  "recipient": {
    "id": "5238d74f-3faa-499f-b26b-4c5e706af064"
  },
  "payer": {
    "id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
  }
}
{
    "id": "0498fc89-d391-478c-863a-fc4c2198300a",
    "fees": [
        {
            "amount": {
                "value": 2.9,
                "currency": "USD"
            },
            "type": "PLASTIQ_SERVICE_FEE",
            "rate": "2.90%"
        }
    ],
    "sourceAmount": {
        "currency": "USD",
        "value": 102.9
    },
    "targetAmount": {
        "currency": "USD",
        "value": 100
    },
    "paymentMethod": {
        "id": "9923ff81-8f49-480b-8c45-1b99796d69a0"
    },
    "recipient": {
        "id": "5238d74f-3faa-499f-b26b-4c5e706af064"
    },
    "payer": {
        "id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
    },
    "details": {
        "accountName": null,
        "accountNumber": null,
        "memo": null
    },
    "status": "CAPTURABLE",
    "statusReasons": [],
    "deliveryDate": "2021-05-13",
    "createdAt": "2021-05-11T10:52:39.000Z",
    "expiresAt": "2021-05-11T23:59:59.000Z",
    "deliveryOptions": [
        {
            "cutoffTime": "2021-05-11T14:59:59.000Z",
            "deliveryDate": "2021-05-11",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T21:59:59.000Z",
            "deliveryDate": "2021-05-12",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T23:59:59.000Z",
            "deliveryDate": "2021-05-13",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        }
    ]
}
{
    "payer": {
        "id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
    },
    "deliveryDate": "2021-03-11"
}
{
    "id": "0498fc89-d391-478c-863a-fc4c2198300a",
    "fees": [
        {
            "amount": {
                "value": 2.9,
                "currency": "USD"
            },
            "type": "PLASTIQ_SERVICE_FEE",
            "rate": "2.90%"
        }
    ],
    "sourceAmount": {
        "currency": "USD",
        "value": 102.9
    },
    "targetAmount": {
        "currency": "USD",
        "value": 100
    },
    "paymentMethod": {
        "id": "9923ff81-8f49-480b-8c45-1b99796d69a0"
    },
    "recipient": {
        "id": "5238d74f-3faa-499f-b26b-4c5e706af064"
    },
    "payer": {
        "id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
    },
    "details": {
        "accountName": null,
        "accountNumber": null,
        "memo": null
    },
    "status": "CAPTURABLE",
    "statusReasons": [],
    "deliveryDate": "2021-05-11",
    "createdAt": "2021-05-11T10:52:39.000Z",
    "expiresAt": "2021-05-11T14:59:59.000Z",
    "deliveryOptions": [
        {
            "cutoffTime": "2021-05-11T14:59:59.000Z",
            "deliveryDate": "2021-05-11",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T21:59:59.000Z",
            "deliveryDate": "2021-05-12",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        },
        {
            "cutoffTime": "2021-05-11T23:59:59.000Z",
            "deliveryDate": "2021-05-13",
            "fees": [
            		{
                    "amount": {
        				        "value": 2.9,
    	  		            "currency": "USD"
           		      },
      	    			  "type": "PLASTIQ_SERVICE_FEE",
                    "rate": "2.90%"
                }
            ]
        }
    ]
}

πŸ“˜

Collecting Payment Information Dynamically

Plastiq's Payment Intent object is designed with ultimate flexibility in mind. You can create a Payment Intent with as little or as much information as you wish.

For example, you could decide to omit the Delivery Date in the request payload to create a Payment Intent. If you choose to do this, a delivery date will be automatically selected for the Payment Intent.

The following section speaks at length about how to further utilize Payment Intents to engender dynamic Payment experiences for your customers.


What’s Next