Invalidating Payment Requests

Use this page to understand how to invalidate a payment request

Overview

An invalidated Payment Request will no longer display the option for customers to submit payments when they view the order payment site. Instead, the site will display an error message that explains why the request was invalidated.

📘

Reminder: Delivery Options

This documentation describes an integration with PayLink that does not include delivery of the link to your end user. With this integration, you will be responsible for link delivery by whatever methods you currently utilize.

If you would like to take advantage of PayLink with text and email delivery, please reach out to your sales representative.

You are able to directly control request invalidation in a few ways:

  • You can set an expiration date and time, which will automatically invalidate your Payment Request after the date and time have passed
  • You can send an API call to Skipify to invalidate a previously created Payment Request

Invalidation via the expiration field
At the time of creating a Payment Request, you can set a specific datetime to invalidate it. After that datetime, the request will automatically invalidate and the status of the payment request will be Expired.

API Request

👍

This endpoint uses HMAC

Please read our API Authentication section to ensure you are crafting your request properly.

When you send an API request to invalidate a Payment Request, we ask you to specify one of two reasons for the invalidation, Paid Off Platform or Cancelled By Merchant, so that we can show the correct invalidation message to the user.

The endpoint for this request uses the payment's paymentRequestId, which was originally provided in the response body when you created the Payment Request. To invalidate a payment request, send an API call to:

POST {{baseURL}}/payment-requests/{{paymentRequestId}}/invalidate

Request Body Parameters

The only parameter for this API call is invalidateStatus, which accepts one of two emum values, PaidOffPlatform and CancelledByMerchant:

Parameter NameRequired?TypeDescription
invalidateStatusYesStringPaidOffPlatform
This denotes that the customer paid for this Payment Request somewhere other than via Skipify's hosted checkout solution (off of the Skipify platform).

For instance, if a customer receives an invoice via a Payment Request, but heads to one of your a brick-and-mortar locations and pays using a point-of-sale system, you should to invalidate the payment request with a PaidOffPlatform status to avoid double-charging that customer. If a customer ever interacts with the Payment Request link after this, they will see a message that tells them that the request was already paid.

CancelledByMerchant
Use this for any other reason you might wish to cancel a Payment Request. Skipify will supply a generic message to the customer explaining that the request is no longer valid.
Request Body Example 
{ 
  "invalidateStatus": "PaidOffPlatform"
}

API Response

Response Body Parameters The response body will include all of the elements that you passed to us when you created the Payment Request. It will also include the following additional fields:
NameTypeDescription
statusenum (PaidOffPlatform, CancelledByMerchant)Denotes what status the payment request is in. There are other statuses that can be attached to Payment Requests, but not for the purposes of this API call.

PaidOffPlatform is a request that you have told us (via API call) was paid on a non-Skipify platform

CancelledByMerchant is a request that you have told us (via API call) to invalidate
orderIdstringID of the associated order. This is only set after the customer submits payment. For this API call, it will be null
paymentTimeStampdatetimeThis is a field we use to track when the actual payment went in.

Only populated if the Payment Request was paid using Skipify (PaidOnPlatform). For this API call, it will be null
hashstringThis is a field Skipify uses to track the order.
Response Body Example 
{
    "paymentRequestId": "e3d308b2-4139-404b-a19e-2c13d43c70d8",
    "merchantPaymentRequestId": "ioh7f-m90yu-4nmt5",
    "status": "PaidOffPlatform",
    "total": 10759,
    "subtotal": 6700,
    "tax": 500,
    "shipping": 500,
    "currencyCode": "USD",
    "metadata": {
        "internal_id": "aa1122"
    },
    "expiration": "2022-06-02T21:48:02Z",
    "lineItems": [
        {
            "sku": "Chicken Salad",
            "description": "Tasty and healthy",
            "amount": 1500,
            "category": "Invoice 1167:Birthday Party",
            "externalId": "61e20592-1619-4c0d-b2ad-2a0ca2c848b7"
        },
        {
            "sku": "Birthday Cake",
            "description": "Chocolately goodness",
            "amount": 2200,
            "category": "Invoice 1167:Birthday Party",
            "externalId": "258c1e29-4a72-4bc7-8522-b050c762633c"
        },
        {
            "sku": "Plates and Napkins",
            "description": "Free of charge",
            "amount": null,
            "category": "Invoice 1167:Birthday Party",
            "externalId": "fcfe06cb-a7eb-48fb-9c96-2da689607637"
        },
        {
            "sku": "Case of Craft Beer",
            "description": "Tasty and not healthy",
            "amount": 3000,
            "category": "Invoice 1168:Parent's Afterparty",
            "externalId": "ea01307a-0756-4acd-b8e5-afec60a2b7aa"
        }
    ],
    "orderId": null,
    "paymentTimestamp": null,
    "hash": "35d24dea899c2e328f26efeb8e7464aa6e331a2138260fd6bb8ba25818a5bb52"
}

👍

API Reference

Our API Reference contains additional details about this endpoint and its use.


Updated 5 months ago