Modifying Payment Requests

Use this guide to review how to make changes to payment requests you have previously created

Overview

It is possible for you to modify a Payment Request that you previously created. This is useful for any case where you want to add, remove or modify the items in the request itself. You can only make a change to a Payment Request when it is in an Open status.

📘

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.

Changes can only be made to Payment requests if they are in an Open status. Payment requests can be closed for multiple reasons:

  • A customer paid the request using Skipify's PayLink
  • A Payment Request expired - meaning the date in the expiration field has passed
  • You invalidated the Payment Request using payment-requests/invalidate. This can be done either because the customer paid on a platform that was not Skipify, or if you simply want to cancel it. For more on this see the Invalidating Payment Requests section.

🚧

PUTs can only be performed on Payment Requests in an Open Status

You can determine the status of the Payment Request looking it up in real time. For more information on statuses and how to look them up, please review the Looking Up Payment Requests section.

API Request

👍

This endpoint uses HMAC

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

The payment request endpoint uses the paymentRequestId, which was provided in the response body while creating the Payment Request. To update a payment request, send an API call to:

PUT {{baseURL}}/payment-requests/{{paymentRequestId}}

Request Body Parameters

This request uses the same fields as when Creating Payment Requests:

Parameter NameRequired?TypeDescription
merchantPaymentRequestIdYesstringThis is a unique identifier that you set. For the PUT, make sure this matches to the correct ID you originally set.
subTotalYesintegerThis is the subtotal of the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050.
taxNointeger, nullableThis is the amount of tax for the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050.
tipNointeger, nullableThis is the amount of tip for the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050.
shippingNointeger, nullableThis is the amount of shipping for the Payment Request. The last two digits are cents, so $20.50 would be sent as 2050
metadataNodictionary, nullableYou can use this parameter to attach key-value data to your API call. We do not do anything with this data and simply repeat it back in the API response.

The purpose of this parameter is to allow you to store additional, structured information to your Payment Request, such as unique identifiers that you can use internally.

We allow for up to 10 keys, with names up to 40 characters and values up to 100 characters

Again, Metadata is not used by Skipify in any way, and won't be seen by your customers in our experience. However, be sure to not include any personally identifiable information here!
customerEmailNostring, nullableThis is the customer's email address. We use this field as an identifier for whether or not the customer is registered with Skipify.

If they are, they will be able to skip filling out checkout fields and, after a one-time-passcode, can dive directly into payment.
expirationNodateTime string, nullableThis is an optional parameter you can use to set an expiry on the Payment Request.

Use the format:
yyyy-MM-ddTHH:mm:ssZ

Ex:
2022-06-02T21:48:02Z
lineItemsNoobject, nullableThese are the individual items you would like to show the customer as a part of their checkout.

There are specific rules about how to set line items. See below for more on the linItems object.
Request Body Example 
{ 
  "total": 2000,
  "subtotal":1500, 
  "tax":200, 
  "shipping":300, 
  "merchantPaymentRequestId": "ekdhfke-23kfhd-dfkgld",
  "metadata": {
     "internal_id": "aa112234"
  },
  "customerEmail": "[email protected]",
  "expiration": "2022-05-24T20:49:02Z",
  "lineItems": [ 
    { 
      "sku": "111222333",
      "description": "A fantatsic product",
      "amount": 1500,
      "category": "Invoice 1167"
    } 
  ] 
}

API Response

Response Body Parameters A successful response will return a playback of the items in your original PUT request, along with the following fields:
Parameter NameTypeDescription
orderIdstring, nullableID of the associated order. This is only set after the customer submits payment. It will be null for PUTs
paymentTimeStampstring (dateTime), nullableThis is an internal field we use to track when the actual payment went in. It will be null for PUTs
hashstringThis is an internal field we use to track the order.
statusenum (Open, PaidOffPlatform, CancelledByMerchant, PaidOnPlatform, Expired)Denotes what status the payment request is in.

Note that for this API Call, you will only see the Open status because you can only modify a Payment Request that is Open.

Open is a request that has been created and has not been paid, invalidated or expired

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

PaidOnPlatform is a Payment Request that has been successfully paid using Skipify PayLink

Expired is a Payment Request that has passed the datetime specified by you in the expiration field of the original Payment Request
Response Body Example 
{
    "paymentRequestId": "e315f5c9-0a37-4f8e-9c03-abb766ae9045",
    "merchantPaymentRequestId": "ekdhfke-23kfhd-dfkgld",
    "status": "Open",
    "total": 2000,
    "subtotal": 1500,
    "tax": 200,
    "shipping": 300,
    "currencyCode": "USD",
    "metadata": {
        "internal_id": "aa112234"
    },
    "expiration": "2022-05-24T20:49:02Z",
    "lineItems": [
        {
            "sku": "111222333",
            "description": "A fantatsic product",
            "amount": 1500,
            "category": "Invoice 1167",
            "externalId": "566d016f-e23e-427c-8077-6b8626286c1f"
        }
    ],
    "orderId": null,
    "paymentTimestamp": null,
    "hash": "4de565ef05e5dfddd602f84a2eec462795fe734a20c120ec2ffe7529e0c49276"
}

👍

API Reference

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


Updated 5 months ago