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.
Advatages 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 delivery timeline, 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 Timeframes | The timeframe on which the Payment delivery can be fulfilled | deliveryDate |
Status | The status of the drafted Payment | status |
Expedited | The delivery speed for a payment | isExpedited |
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.85,
"currency": "USD"
},
"type": "PLASTIQ_SERVICE_FEE",
"rate": "2.85%"
}
],
"sourceAmount": {
"currency": "USD",
"value": 102.85
},
"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 00:00:00",
"createdAt": "2021-05-10T17:52:39.000Z",
"expiresAt": "2021-05-11T03:45:39Z"
}
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, which is typically about 15 minutes after the Payment Intent is created, 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
Failure to create the Payment before the expiresAt
date will result in a validation error. When fetching an expired Payment Intent, its status will show as EXPIRED
and will no longer be a valid asset that can be leverage to create a Payment.
Expedited Payments
Connect offers expedited payments for Check recipients. This option reduces SLAs to 2 business days but will incur additional delivery fees.
Expedited Check | |
---|---|
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.85% (Plastiq Fee) + 0.5% (Base Fee) + $24.99 (FedEx Priority Overnight fee) + $10 (Handling Fee)* |
*Handling fee waived on payments with a principal over $3,000.
†Waived on payments with a principal over $20,000.
Payment Intent Flexibility
Now let's consider a scenario where a Payer begins to enter payment information but does not have credit card information readily available.
They may want to save their payment progress, add a credit card to their account, and then attach the Payment Method to their Payment Intent at a later point in time.
The Payment Intent endpoint can flexibly take in an incomplete payload and return the appropriate status
and statusReasons
to provide feedback on how to update the Payment Intent into a 'CAPTURABLE' status for payment submission.
Here is an example of a Payment Intent response that was returned without a Payment Method Id.
{
"id": "0498fc89-d391-478c-863a-fc4c2198300a",
"fees": [
{
"amount": {
"value": 2.85,
"currency": "USD"
},
"type": "PLASTIQ_SERVICE_FEE",
"rate": "2.85%"
}
],
"sourceAmount": {
"currency": "USD",
"value": 102.85
},
"targetAmount": {
"currency": "USD",
"value": 100
},
"paymentMethod": {
"id": null
},
"recipient": {
"id": "5238d74f-3faa-499f-b26b-4c5e706af064"
},
"payer": {
"id": "d75d7431-a4b3-46e0-a296-efb3d7fd08b8"
},
"details": {
"accountName": null,
"accountNumber": null,
"memo": null
},
"status": "NOT_CAPTURABLE",
"statusReasons": [
{
"code": "MISSING_PAYMENT_METHOD",
"message": "Payment Intent does not have a Payment Method ID"
}
],
"deliveryDate": "2021-05-13 00:00:00",
"createdAt": "2021-05-10T17:52:39.000Z",
"expiresAt": "2021-05-11T03:45:39Z"
}
Attempts to make a request to POST Payments with a Payment Intent Id that is in a status
of 'NOT_CAPTURABLE' will result in a validation error.
To fix this, you will need to update the Payment Intent with a Payment Method Id.
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 Payment Method ID in the request payload to create a Payment Intent. If you choose to do this, the Payment Intent will have a
status
of 'NOT_CAPTURABLE' and astatusReasons
code of 'MISSING_PAYMENT_METHOD'.
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