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

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

1. Include your API key in the x-api-key parameter in the header of a POST request.
2. Send your request to https://identity.payroc.com/authorize.

Example request

1
curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

1
{
2
  "access_token": "eyJhbGc....adQssw5c",
3
  "expires_in": 3600,
4
  "scope": "service_a service_b",
5
  "token_type": "Bearer"
6
}

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/ \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "type": "multiUse",
7
  "merchantReference": "LinkRef6543",
8
  "order": {
9
    "charge": {
10
      "type": "prompt",
11
      "currency": "AED"
12
    }
13
  },
14
  "authType": "sale",
15
  "paymentMethods": [
16
    "card"
17
  ]
18
}'

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
  "type": "multiUse",
3
  "paymentLinkId": "JZURRJBUPS",
4
  "merchantReference": "LinkRef6543",
5
  "order": {
6
    "description": "Pie It Forward charitable trust donation",
7
    "charge": {
8
      "type": "prompt",
9
      "currency": "USD"
10
    }
11
  },
12
  "authType": "sale",
13
  "paymentMethods": [
14
    "card",
15
    "bankTransfer"
16
  ],
17
  "customLabels": [
18
    {
19
      "element": "paymentButton",
20
      "label": "SUPPORT US"
21
    }
22
  ],
23
  "assets": {
24
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
25
    "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"
26
  },
27
  "status": "active",
28
  "createdOn": "2024-09-24"
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/ \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "sharingMethod": "email",
7
  "recipients": [
8
    {
9
      "name": "Sarah Hazel Hopper",
10
      "email": "[email protected]"
11
    }
12
  ]
13
}'

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