Share payment link

Browse API reference

POST/payment-links/{paymentLinkId}/sharing-eventssharePaymentLink

Use this method to email a payment link to a customer.

To email a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the Create Payment Link method.

Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link.

In the request, you must provide the recipient's name and email address.

In the response, our gateway returns a sharingEventId, which you can use to List Payment Link Sharing Events.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	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.
`paymentLinkId`Required	path	`string`	Unique identifier that we assigned to the payment link.

Request body

application/json

Field Edit request inputs →

emailobject
Object that contains the information about a sharing event that the merchant sent by email.
- merchantCopyboolean
  Indicates if we send a copy of the email to the merchant. By default, we don't send a copy to the merchant.
- messagestring
  Message that the merchant sends with the payment link.≤ 1024 chars
- recipientsobject[]required
  Array that contains the recipients of the payment link.
  - emailstringrequired
    Recipient's email address.6–128 chars
  - namestringrequired
    Recipient's name.1–48 chars
- sharingMethodstringrequired
  Method that the merchant uses to share the payment link.email

Responses

Successful request. We return a polymorphic object that contains information about how the merchant shared a payment link.

201 Created · application/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"
}

Response schema · 9 fields

emailobject
Object that contains the information about a sharing event that the merchant sent by email.
- dateTimestringdate-time
  Date and time that the merchant shared the link. Our gateway returns this value in the ISO 8601 format.
- merchantCopyboolean
  Indicates if we send a copy of the email to the merchant. By default, we don't send a copy to the merchant.
- messagestring
  Message that the merchant sends with the payment link.≤ 1024 chars
- recipientsobject[]required
  Array that contains the recipients of the payment link.
  - emailstringrequired
    Recipient's email address.6–128 chars
  - namestringrequired
    Recipient's name.1–48 chars
- sharingEventIdstring
  Unique identifier that we assigned to the sharing event.10–10 chars
- sharingMethodstringrequired
  Method that the merchant uses to share the payment link.email

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

collect-with-payment-link

Share payment link

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer