Overview

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

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.

*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.