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:

  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

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 a statusReasons 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.


Did this page help you?