Partially update payment link

Browse API reference

PATCH/payment-links/{paymentLinkId}updatePaymentLink

Use this method to partially update a payment link. Structure your request to follow the RFC 6902 standard.

To update a payment link, you need its paymentLinkId, which we sent you in the response of the Create Payment Link method.

Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link.

You can update the following properties of a multi-use link:

expiresOn parameter - Expiration date of the link.
customLabels object - Label for the payment button.
credentialOnFile object - Settings for saving the customer's payment details.

You can update the following properties of a single-use link:

expiresOn parameter - Expiration date of the link.
authType parameter - Transaction type of the payment link.
amount parameter - Total amount of the transaction.
currency parameter - Currency of the transaction.
description parameter - Brief description of the transaction.
customLabels object - Label for the payment button.
credentialOnFile object - Settings for saving the customer's payment details.

Note: When a merchant updates a single-use link, we update the payment URL and HTML code in the assets object. The customer can't use the original link to make a payment.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.
`paymentLinkId`Required	path	`string`	Unique identifier that we assigned to the payment link.

Request body

application/json · required

Field Edit request inputs →

Patch Add Operationobject
A Patch Add Operation.
- opstringrequired
  add operation.add
- pathstringrequired
  Location where you want to add the value. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to add to the resource.
Patch Remove Operationobject
A Patch Remove Operation.
- opstringrequired
  remove operation.remove
- pathstringrequired
  Location of the value that you want to remove. The format for this value is JSON Pointer.
Patch Replace Operationobject
A Patch Replace Operation.
- opstringrequired
  replace operation.replace
- pathstringrequired
  Location of the value that you want to replace. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to use as the replacement.
Patch Move Operationobject
A Patch Move Operation.
- fromstringrequired
  Location of the value that you want to move. The format for this value is JSON Pointer.
- opstringrequired
  move operation.move
- pathstringrequired
  Location where you want to move the value to. The format for this value is JSON Pointer.
Patch Copy Operationobject
A Patch Copy Operation.
- fromstringrequired
  Location of the value that you want to copy. The format for this value is JSON Pointer.
- opstringrequired
  copy operation.copy
- pathstringrequired
  Location where you want to copy the value to. The format for this value is JSON Pointer.
Patch Test Operationobject
A Patch Test Operation.
- opstringrequired
  test operation.test
- pathstringrequired
  Location of the value that you want to test. The format for this value is JSON Pointer.
- valueobjectrequired
  Value that you want to compare with the current value at the path.

Responses

Successful request. We updated the payment link and return a polymorphic object that contains payment link information. The value of the type parameter determines which variant you should use:

multiUse - Create a link that the merchant can use to take multiple payments.
singleUse - Create a link that the merchant can use for only one payment.

200 OK · application/json

{
  "assets": {
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\"\ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif;\ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n",
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d"
  },
  "authType": "sale",
  "createdOn": "2024-09-24",
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    },
    {
      "element": "paymentButton",
      "label": "DONATE NOW"
    }
  ],
  "merchantReference": "LinkRef6543",
  "order": {
    "charge": {
      "currency": "USD",
      "type": "prompt"
    },
    "description": "Pie It Forward charitable trust donation"
  },
  "paymentLinkId": "JZURRJBUPS",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "status": "active",
  "type": "multiUse"
}

Response schema · 43 of 57 fields

multiUseobject
Object that contains information about a multi-use payment link.
- assetsobject
  Object that contains shareable assets for the payment link.
  - paymentButtonstringhtmlrequired
    HTML code for the payment link. You can embed the HTML code in the merchant's website.
  - paymentUrlstringrequired
    URL of the payment link.
- authTypestringrequired
  Type of transaction.salepreAuthorization
- createdOnstringdate
  Date that the merchant created the link. The format of this value is YYYY-MM-DD.
- credentialOnFileobject
  Object that contains information about saving the customer’s payment details.
  - mitAgreementstring
    Indicates how the merchant can use the customer’s card details, as agreed by the customer: unscheduled Transactions for a fixed or variable amount that are run at a certain pre-defined event. recurring Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
  - tokenizeboolean
    Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
- customLabelsobject[]
  Array of customLabel objects. Note: You can change the label of the payment button only.
  - elementstring
    Element that you want to provide a custom label for.paymentButton
  - labelstring
    Custom label to display on the element.1–24 chars
- expiresOnstringdate
  Last date that the customer can use the payment link. The format of this value is YYYY-MM-DD. Note: If you don't provide an expiration date, the default expiration period applies. You can change the default expiration period on the Self-Care Portal.
- merchantReferencestringrequired
  Unique identifier that the merchant assigned to the payment.1–48 chars
- orderobjectrequired
  Object that contains information about the order.
  - chargeobjectrequired
    Polymorphic object that indicates who enters the amount for the payment link. The value of the type parameter determines which variant you should use: prompt Customer enters the amount. preset Merchant sets the amount.+7 more fields at deeper levels — see the full spec
  - descriptionstring
    A brief description of the transaction.≤ 1024 chars
- paymentLinkIdstring
  Unique identifier that we assigned to the payment link.10–10 chars
- paymentMethodsstring[]required
  Payment methods that the merchant accepts. Note: If a payment is a pre-authorization, the customer must pay by card.
- statusstring
  Status of the payment link. The value is one of the following: active Payment link is active. completed Customer has paid. deactivated Merchant has deactivated the link. expired Payment link has expired.activecompleteddeactivatedexpired
- typestringrequired
  Type of link. The merchant can use a multi-use link to take multiple payments.multiUse
singleUseobject
Object that contains information about a single-use payment link.
- assetsobject
  Object that contains shareable assets for the payment link.
  - paymentButtonstringhtmlrequired
    HTML code for the payment link. You can embed the HTML code in the merchant's website.
  - paymentUrlstringrequired
    URL of the payment link.
- authTypestringrequired
  Type of transaction.salepreAuthorization
- createdOnstringdate
  Date that the merchant created the link. The format of this value is YYYY-MM-DD.
- credentialOnFileobject
  Object that contains information about saving the customer’s payment details.
  - mitAgreementstring
    Indicates how the merchant can use the customer’s card details, as agreed by the customer: unscheduled Transactions for a fixed or variable amount that are run at a certain pre-defined event. recurring Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don’t have a fixed duration and run until the customer cancels the agreement. installment Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
  - tokenizeboolean
    Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
- customLabelsobject[]
  Array of customLabel objects. Note: You can change the label of the payment button only.
  - elementstring
    Element that you want to provide a custom label for.paymentButton
  - labelstring
    Custom label to display on the element.1–24 chars
- expiresOnstringdaterequired
  Last date that the customer can use the payment link. The format of this value is YYYY-MM-DD.
- merchantReferencestringrequired
  Unique identifier that the merchant assigned to the payment.1–48 chars
- orderobjectrequired
  Object that contains information about the order.
  - chargeobjectrequired
    Polymorphic object that indicates who enters the amount for the payment link. The value of the type parameter determines which variant you should use: prompt Customer enters the amount. preset Merchant sets the amount.+7 more fields at deeper levels — see the full spec
  - descriptionstring
    A brief description of the transaction.≤ 1024 chars
  - orderIdstringrequired
    Unique identifier that the merchant assigned to the order.1–24 chars
- paymentLinkIdstring
  Unique identifier that we assigned to the payment link.10–10 chars
- paymentMethodsstring[]required
  Payment methods that the merchant accepts. Note: If the payment is a pre-authorization, the customer must pay by card.
- statusstring
  Status of the payment link. The value is one of the following: active Payment link is active. completed Customer has paid. deactivated Merchant has deactivated the link. expired Payment link has expired.activecompleteddeactivatedexpired
- typestringrequired
  Type of link. The merchant can use this link for only one payment.singleUse

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

collect-with-payment-link

Partially update payment link

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer