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
| Attribute | Description | API Field Name |
|---|---|---|
| Source Amount | The Payment dollar amount that will be withdrawn from the Payment Method | sourceAmount |
| Target Amount | The Payment dollar amount that will be disbursed to the Recipient | targetAmount |
| Payer | The individual or business making the Payment | paymentIntent.id |
| Payment Method | The financial instrument used to fund the Payment | paymentMethod.id |
| Recipient | The individual or business receiving the Payment | recipient.id |
| Remittance Details | The 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 |
| Fees | The fees applied on the Payment | fees |
| Delivery Date | The date on which the Payment delivery can be fulfilled by | deliveryDate |
| Status | The status of the drafted Payment | status |
| Is Expedited | A flag indicating whether the payment should be expedited Note: if true, the fastest available delivery date will be automatically chosen | isExpedited |
| Delivery Options | The list of available delivery dates with their corresponding fees and when the date is valid until | deliveryOptions |
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:
- Time of creation
- Recipient's receiving method (ACH, Check, Wire, or EFT),
- Day of the week
- 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 Timeframe | 1 business day |
| Expedited Delivery Pricing | 2.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 Timeframe | 2 business days |
| Expedited Delivery Pricing | 2.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.
Updated 9 months ago