Skip to content
payrocdevelopers

Create payment link

Browse API reference

POST/processing-terminals/{processingTerminalId}/payment-linkscreatePaymentLink

Use this method to create a payment link that a customer can use to make a payment for goods or services.

The request includes the following settings:

  • type - Indicates whether the link can be used only once or if it can be used multiple times.
  • authType - Indicates whether the transaction is a sale or a pre-authorization.
  • paymentMethod - Indicates the payment methods that the merchant accepts.
  • charge - Indicates whether the merchant or the customer enters the amount for the transaction.

If your request is successful, our gateway returns a paymentLinkId, which you can use to perform follow-on actions.

Note: To share the payment link with a customer, use our Share Payment Link method.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

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.

processingTerminalIdRequiredpathstring

Unique identifier that we assigned to the terminal.

Request body

application/json · required
Field Edit request inputs →
  • multiUseobject
    Object that contains information about a multi-use payment link.
    • authTypestringrequired
      Type of transaction.salepreAuthorization
    • 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
    • paymentMethodsstring[]required
      Payment methods that the merchant accepts. Note: If a payment is a pre-authorization, the customer must pay by card.
    • 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.
    • authTypestringrequired
      Type of transaction.salepreAuthorization
    • 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
    • paymentMethodsstring[]required
      Payment methods that the merchant accepts. Note: If the payment is a pre-authorization, the customer must pay by card.
    • typestringrequired
      Type of link. The merchant can use this link for only one payment.singleUse

Responses

Successful request. We 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.
201 Created · application/json
{
  "assets": {
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206\"\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;\">PAY NOW</a>\n",
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206"
  },
  "authType": "sale",
  "createdOn": "2024-07-24",
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "PAY NOW"
    }
  ],
  "expiresOn": "2024-08-02",
  "merchantReference": "LinkRef7654",
  "order": {
    "charge": {
      "amount": 4999,
      "currency": "USD",
      "type": "preset"
    },
    "description": "Large Pepperoni Pizza",
    "orderId": "OrderRef7654"
  },
  "paymentLinkId": "CKHP6VVWYT",
  "paymentMethods": [
    "card"
  ],
  "status": "active",
  "type": "singleUse"
}
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

Used in workflows

collect-with-payment-link

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer