Create and share a payment link

Use our Payment Links feature to create a payment link that the merchant can email to customers to pay for goods and services. The request to create a payment link contains the following settings for the payment link:

• 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 customer enters the amount for the transaction.

When the gateway creates the link, it returns the paymentLinkId that you use in the request to share the payment link.

Integration steps

Step 1. Create a payment link.
Step 2. Share a payment link.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Headers

To create the header of each GET request, you must include the following parameters:

• Content-Type: Include application/json as the value for this parameter.
• Authorization: Include your Bearer token in this parameter.

1
curl
2
  -H "Content-Type: application/json"
3
  -H "Authorization: <Bearer token>"

To create the header of each POST request, you must include the following parameters:

• Content-Type: Include application/json as the value for this parameter.
• Authorization: Include your Bearer token in this parameter.
• Idempotency-Key: Include a UUID v4 to make the request idempotent.

1
curl
2
  -H "Content-Type: application/json"
3
  -H "Authorization: <Bearer token>"
4
  -H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Step 1. Create a payment link

To create a payment link, send a POST request to our Processing Terminals endpoint.

Request parameters

To create the body of your request, use the following parameters:

Example request

1
curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/payment-links \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "authType": "sale",
7
  "customLabels": [
8
    {
9
      "element": "paymentButton",
10
      "label": "SUPPORT US"
11
    }
12
  ],
13
  "merchantReference": "LinkRef6543",
14
  "order": {
15
    "charge": {
16
      "currency": "USD",
17
      "type": "prompt"
18
    },
19
    "description": "Pie It Forward charitable trust donation"
20
  },
21
  "paymentMethods": [
22
    "card",
23
    "bankTransfer"
24
  ],
25
  "type": "multiUse"
26
}'

Response fields

If your request is successful, our gateway returns a paymentLinkId. Save the paymentLinkId so that you can include it in the request to share the link. The response contains the following fields:

Example response

1
{
2
  "assets": {
3
    "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",
4
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d"
5
  },
6
  "authType": "sale",
7
  "createdOn": "2024-09-24",
8
  "customLabels": [
9
    {
10
      "element": "paymentButton",
11
      "label": "SUPPORT US"
12
    }
13
  ],
14
  "merchantReference": "LinkRef6543",
15
  "order": {
16
    "charge": {
17
      "currency": "USD",
18
      "type": "prompt"
19
    },
20
    "description": "Pie It Forward charitable trust donation"
21
  },
22
  "paymentLinkId": "JZURRJBUPS",
23
  "paymentMethods": [
24
    "card",
25
    "bankTransfer"
26
  ],
27
  "status": "active",
28
  "type": "multiUse"
29
}

Step 2. Share a payment link

To share a payment link, send a POST request to our Payment Links endpoint that includes the paymentLinkId of the link you want to share.

Request parameters

To create the body of your request, use the following parameters:

Example request

1
curl -X POST https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "merchantCopy": true,
7
  "message": "Dear Sarah,\n\nYour insurance is expiring this month.\nPlease, pay the renewal fee by the end of the month to renew it.\n",
8
  "recipients": [
9
    {
10
      "email": "[email protected]",
11
      "name": "Sarah Hazel Hopper"
12
    }
13
  ],
14
  "sharingMethod": "email"
15
}'

Response fields

If your request is successful, our gateway shares the payment link with the recipients. The response contains the following fields:

Example response

1
{
2
  "dateTime": "2024-07-02T15:30:00Z",
3
  "message": "Dear Sarah,\n\nYou can pay for your order via the link below.\n",
4
  "recipients": [
5
    {
6
      "email": "[email protected]",
7
      "name": "Sarah Hazel Hopper"
8
    }
9
  ],
10
  "sharingEventId": "GTZH5WVXK9",
11
  "sharingMethod": "email"
12
}