Create and share a payment link

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

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.

Shell

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.

Shell

curl
  -H "Content-Type: application/json"
  -H "Authorization: <Bearer token>"
  -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.

Environment	URL
Test	https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links
Production	https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/payment-links

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

Example request

<### Request

POST https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/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

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

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()

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

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"
}

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
Production	https://api.payroc.com/v1/payment-links/{paymentLinkId}/sharing-events

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

Example request

<### Request

POST https://api.payroc.com/v1/payment-links/{paymentLinkId}/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

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

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()

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

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"
}

Integration steps

Before you begin

Headers

Errors

Step 1. Create a payment link

Request parameters

Example request

Response fields

Example response

Request parameters

Example request

Response fields

Example response

Browse guides

Menu

Sign out

Talk to an engineer

Integration steps

Before you begin

Headers

Errors

Step 1. Create a payment link

Request parameters

Example request

Response fields

Example response

Step 2. Share a payment link

Request parameters

Example request

Response fields

Example response