# Create and share a payment link

Create a payment link and share it with customers by sending POST requests to the Processing Terminals and Payment Links endpoints.

An AI skill is available for this guide, get it on the [Skills Marketplace (GitHub)](https://github.com/payroc/skills).

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.

<a id="integration-steps"></a>
## Integration steps

**Step 1.** Create a payment link. \\

**Step 2.** Share a payment link.

<a id="before-you-begin"></a>
## Before you begin

[Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors).

<a id="headers"></a>
### 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.

```sh
curl
  -H "Content-Type: application/json"
  -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.

```sh
curl
  -H "Content-Type: application/json"
  -H "Authorization: <Bearer token>"
  -H "Idempotency-Key: <UUID v4>"
```

<a id="errors"></a>
### Errors

If your request is unsuccessful, we return an error. For more information about errors, see [Errors](/api/errors).

<a id="step-1-create-a-payment-link"></a>
## Step 1. Create a payment link

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

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/processing-terminals/\{processingTerminalId\}/payment-links](https://api.uat.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/payment-links) |
| Production | [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId\}/payment-links](https://api.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/payment-links) |

<a id="request-parameters"></a>
### Request parameters

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

\<\#\#\# Schema (`request.body`)

[Request body schema for `POST /processing-terminals/{processingTerminalId}/payment-links`](/api/create-payment-link)

<a id="example-request"></a>
### Example request

\<\#\#\# Request

POST [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId\}/payment-links](https://api.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/payment-links)

**`Multi-use payment link`**

```curl
curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/payment-links \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "authType": "sale",
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "merchantReference": "LinkRef6543",
  "order": {
    "charge": {
      "currency": "USD",
      "type": "prompt"
    },
    "description": "Pie It Forward charitable trust donation"
  },
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "type": "multiUse"
}'
```

**`Multi-use payment link`**

```python
import requests

url = "https://api.payroc.com/v1/processing-terminals/1234001/payment-links"

payload = {
    "authType": "sale",
    "customLabels": [
        {
            "element": "paymentButton",
            "label": "SUPPORT US"
        }
    ],
    "merchantReference": "LinkRef6543",
    "order": {
        "charge": {
            "currency": "USD",
            "type": "prompt"
        },
        "description": "Pie It Forward charitable trust donation"
    },
    "paymentMethods": ["card", "bankTransfer"],
    "type": "multiUse"
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Multi-use payment link`**

```javascript
const url = 'https://api.payroc.com/v1/processing-terminals/1234001/payment-links';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"authType":"sale","customLabels":[{"element":"paymentButton","label":"SUPPORT US"}],"merchantReference":"LinkRef6543","order":{"charge":{"currency":"USD","type":"prompt"},"description":"Pie It Forward charitable trust donation"},"paymentMethods":["card","bankTransfer"],"type":"multiUse"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Multi-use payment link`**

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/processing-terminals/1234001/payment-links"

	payload := strings.NewReader("{\n  \"authType\": \"sale\",\n  \"customLabels\": [\n    {\n      \"element\": \"paymentButton\",\n      \"label\": \"SUPPORT US\"\n    }\n  ],\n  \"merchantReference\": \"LinkRef6543\",\n  \"order\": {\n    \"charge\": {\n      \"currency\": \"USD\",\n      \"type\": \"prompt\"\n    },\n    \"description\": \"Pie It Forward charitable trust donation\"\n  },\n  \"paymentMethods\": [\n    \"card\",\n    \"bankTransfer\"\n  ],\n  \"type\": \"multiUse\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Multi-use payment link`**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/processing-terminals/1234001/payment-links")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"authType\": \"sale\",\n  \"customLabels\": [\n    {\n      \"element\": \"paymentButton\",\n      \"label\": \"SUPPORT US\"\n    }\n  ],\n  \"merchantReference\": \"LinkRef6543\",\n  \"order\": {\n    \"charge\": {\n      \"currency\": \"USD\",\n      \"type\": \"prompt\"\n    },\n    \"description\": \"Pie It Forward charitable trust donation\"\n  },\n  \"paymentMethods\": [\n    \"card\",\n    \"bankTransfer\"\n  ],\n  \"type\": \"multiUse\"\n}"

response = http.request(request)
puts response.read_body
```

**`Multi-use payment link`**

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/processing-terminals/1234001/payment-links")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authType\": \"sale\",\n  \"customLabels\": [\n    {\n      \"element\": \"paymentButton\",\n      \"label\": \"SUPPORT US\"\n    }\n  ],\n  \"merchantReference\": \"LinkRef6543\",\n  \"order\": {\n    \"charge\": {\n      \"currency\": \"USD\",\n      \"type\": \"prompt\"\n    },\n    \"description\": \"Pie It Forward charitable trust donation\"\n  },\n  \"paymentMethods\": [\n    \"card\",\n    \"bankTransfer\"\n  ],\n  \"type\": \"multiUse\"\n}")
  .asString();
```

**`Multi-use payment link`**

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/processing-terminals/1234001/payment-links', [
  'body' => '{
  "authType": "sale",
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "merchantReference": "LinkRef6543",
  "order": {
    "charge": {
      "currency": "USD",
      "type": "prompt"
    },
    "description": "Pie It Forward charitable trust donation"
  },
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "type": "multiUse"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();
```

**`Multi-use payment link`**

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/processing-terminals/1234001/payment-links");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"authType\": \"sale\",\n  \"customLabels\": [\n    {\n      \"element\": \"paymentButton\",\n      \"label\": \"SUPPORT US\"\n    }\n  ],\n  \"merchantReference\": \"LinkRef6543\",\n  \"order\": {\n    \"charge\": {\n      \"currency\": \"USD\",\n      \"type\": \"prompt\"\n    },\n    \"description\": \"Pie It Forward charitable trust donation\"\n  },\n  \"paymentMethods\": [\n    \"card\",\n    \"bankTransfer\"\n  ],\n  \"type\": \"multiUse\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Multi-use payment link`**

```swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "authType": "sale",
  "customLabels": [
    [
      "element": "paymentButton",
      "label": "SUPPORT US"
    ]
  ],
  "merchantReference": "LinkRef6543",
  "order": [
    "charge": [
      "currency": "USD",
      "type": "prompt"
    ],
    "description": "Pie It Forward charitable trust donation"
  ],
  "paymentMethods": ["card", "bankTransfer"],
  "type": "multiUse"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/processing-terminals/1234001/payment-links")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: \{ (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

<a id="response-fields"></a>
### 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:

\<\#\#\# Schema (`response.body`)

[Response body schema for `POST /processing-terminals/{processingTerminalId}/payment-links`](/api/create-payment-link)

<a id="example-response"></a>
### Example response

\<\#\#\# Response (201)

```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"
    }
  ],
  "merchantReference": "LinkRef6543",
  "order": {
    "charge": {
      "currency": "USD",
      "type": "prompt"
    },
    "description": "Pie It Forward charitable trust donation"
  },
  "paymentLinkId": "JZURRJBUPS",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "status": "active",
  "type": "multiUse"
}
```

<a id="step-2-share-a-payment-link"></a>
## 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.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/payment-links/\{paymentLinkId\}/sharing-events](https://api.uat.payroc.com/v1/payment-links/%7BpaymentLinkId%7D/sharing-events) |
| Production | [https://api.payroc.com/v1/payment-links/\{paymentLinkId\}/sharing-events](https://api.payroc.com/v1/payment-links/%7BpaymentLinkId%7D/sharing-events) |

<a id="request-parameters-1"></a>
### Request parameters

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

\<\#\#\# Schema (`request.body`)

[Request body schema for `POST /payment-links/{paymentLinkId}/sharing-events`](/api/share-payment-link)

<a id="example-request-1"></a>
### Example request

\<\#\#\# Request

POST [https://api.payroc.com/v1/payment-links/\{paymentLinkId\}/sharing-events](https://api.payroc.com/v1/payment-links/%7BpaymentLinkId%7D/sharing-events)

**`Share a payment link`**

```curl
curl -X POST https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "merchantCopy": true,
  "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",
  "recipients": [
    {
      "email": "sarah.hopper@example.com",
      "name": "Sarah Hazel Hopper"
    }
  ],
  "sharingMethod": "email"
}'
```

**`Share a payment link`**

```python
import requests

url = "https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events"

payload = {
    "merchantCopy": True,
    "message": "Dear Sarah,

Your insurance is expiring this month.
Please, pay the renewal fee by the end of the month to renew it.
",
    "recipients": [
        {
            "email": "sarah.hopper@example.com",
            "name": "Sarah Hazel Hopper"
        }
    ],
    "sharingMethod": "email"
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Share a payment link`**

```javascript
const url = 'https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"merchantCopy":true,"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","recipients":[{"email":"sarah.hopper@example.com","name":"Sarah Hazel Hopper"}],"sharingMethod":"email"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Share a payment link`**

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events"

	payload := strings.NewReader("{\n  \"merchantCopy\": true,\n  \"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\",\n  \"recipients\": [\n    {\n      \"email\": \"sarah.hopper@example.com\",\n      \"name\": \"Sarah Hazel Hopper\"\n    }\n  ],\n  \"sharingMethod\": \"email\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Share a payment link`**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantCopy\": true,\n  \"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\",\n  \"recipients\": [\n    {\n      \"email\": \"sarah.hopper@example.com\",\n      \"name\": \"Sarah Hazel Hopper\"\n    }\n  ],\n  \"sharingMethod\": \"email\"\n}"

response = http.request(request)
puts response.read_body
```

**`Share a payment link`**

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantCopy\": true,\n  \"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\",\n  \"recipients\": [\n    {\n      \"email\": \"sarah.hopper@example.com\",\n      \"name\": \"Sarah Hazel Hopper\"\n    }\n  ],\n  \"sharingMethod\": \"email\"\n}")
  .asString();
```

**`Share a payment link`**

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events', [
  'body' => '{
  "merchantCopy": true,
  "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",
  "recipients": [
    {
      "email": "sarah.hopper@example.com",
      "name": "Sarah Hazel Hopper"
    }
  ],
  "sharingMethod": "email"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();
```

**`Share a payment link`**

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchantCopy\": true,\n  \"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\",\n  \"recipients\": [\n    {\n      \"email\": \"sarah.hopper@example.com\",\n      \"name\": \"Sarah Hazel Hopper\"\n    }\n  ],\n  \"sharingMethod\": \"email\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Share a payment link`**

```swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "merchantCopy": true,
  "message": "Dear Sarah,

Your insurance is expiring this month.
Please, pay the renewal fee by the end of the month to renew it.
",
  "recipients": [
    [
      "email": "sarah.hopper@example.com",
      "name": "Sarah Hazel Hopper"
    ]
  ],
  "sharingMethod": "email"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: \{ (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

<a id="response-fields-1"></a>
### Response fields

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

\<\#\#\# Schema (`response.body`)

[Response body schema for `POST /payment-links/{paymentLinkId}/sharing-events`](/api/share-payment-link)

<a id="example-response-1"></a>
### Example response

\<\#\#\# Response (201)

```json
{
  "dateTime": "2024-07-02T15:30:00Z",
  "message": "Dear Sarah,\n\nYou can pay for your order via the link below.\n",
  "recipients": [
    {
      "email": "sarah.hopper@example.com",
      "name": "Sarah Hazel Hopper"
    }
  ],
  "sharingEventId": "GTZH5WVXK9",
  "sharingMethod": "email"
}
```