Skip to main content
POST
/
payment-links
Create payment link
using RestSharp;


var options = new RestClientOptions("https://api.sandbox.{id}.gr4vy.app/payment-links");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n  \"amount\": 1299,\n  \"currency\": \"USD\",\n  \"country\": \"US\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);
{
  "id": "8d3fe99b-1422-42e6-bbb3-932d95ae5f79",
  "type": "payment_link",
  "amount": 1299,
  "currency": "USD",
  "created_at": "2022-01-01T12:00:00+00:00",
  "updated_at": "2022-01-01T12:00:00+00:00",
  "expires_at": "2022-01-01T12:00:00+00:00",
  "status": "active",
  "external_identifier": "payment-link-123",
  "statement_descriptor": {
    "name": "GR4VY",
    "description": "Card payment",
    "city": "London",
    "country": "US",
    "phone_number": "+1234567890",
    "url": "www.gr4vy.com"
  },
  "locale": "en",
  "merchant_name": "Gr4vy",
  "merchant_url": "https://gr4vy.com",
  "merchant_banner_url": "https://gr4vy.com/banner.png",
  "merchant_color": "#FF0000",
  "merchant_message": "Thank you for shopping with us!",
  "merchant_terms_and_conditions_url": "https://gr4vy.com/terms",
  "merchant_favicon_url": "https://gr4vy.com/favicon.png",
  "country": "US",
  "intent": "authorize",
  "return_url": "https://gr4vy.com/return",
  "cart_items": [
    {
      "name": "GoPro HERO9 Camcorder",
      "quantity": 1,
      "unit_amount": 37999,
      "discount_amount": 0,
      "tax_amount": 0,
      "external_identifier": "item-789123",
      "sku": "sku-789123",
      "product_url": "https://example.com/items/gopro",
      "image_url": "https://example.com/images/items/gopro.png",
      "categories": [
        "<string>"
      ],
      "product_type": "physical",
      "seller_country": "US"
    }
  ],
  "metadata": {
    "key": "value"
  },
  "payment_source": "recurring",
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "billing_details": {
      "type": "billing-details",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "display_name": "John L.",
    "external_identifier": "user-789123",
    "account_number": "1234567"
  },
  "shipping_details": {
    "type": "shipping-details",
    "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
    "buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
    "first_name": "John",
    "last_name": "Lunn",
    "email_address": "john@example.com",
    "phone_number": "+1234567890",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  }
}
This endpoint requires the payment-links.write scope.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating a new payment link.

​
amount
number
required

The amount to request payment for.

Required range: 1 <= x <= 99999999
Example:

1299

​
currency
string
required

The ISO-4217 currency code for the payment.

Example:

"USD"

​
country
string
required

The 2-letter ISO code of the country of the transaction. This is used to filter the payment services that is used to process the transaction.

Example:

"US"

​
buyer
Buyer · object

Guest buyer details provided inline. No buyer resource will be created on Gr4vy when used.

​
expires_at
string<date-time> | null

The date and time when this payment link expires. Defaults to 24 hours from creation.

Example:

"2022-01-01T12:00:00+00:00"

​
connection_options
Connection Options · object

Allows for passing optional configuration per connection to take advantage of connection specific features. When provided, the data is only passed to the target connection type to prevent sharing configuration across connections.

Please note that each of the keys this object are in kebab-case, for example cybersource-anti-fraud as they represent the ID of the connector. All the other keys will be snake case, for example merchant_defined_data or camel case to match an external API that the connector uses.

​
external_identifier
string | null

A value that can be used to match the payment link against your own records. This will also be applied to any transaction.

Required string length: 1 - 200
Example:

"payment-link-123"

​
statement_descriptor
Statement descriptor · object

The statement descriptor is the text to be shown on the buyer's statements.

The specific usage of these fields will depend on the capabilities of the underlying PSP and bank. As a typical example, 'name' and 'description' could be concatenated using '* ' as a separator, and then the resulting descriptor would be truncated to 22 characters by the issuing bank.

​
locale
enum<string> | null

The locale used to translate text within the payment link.

Available options:
en,
en-GB,
es,
pt,
pt-BR
Example:

"en"

​
merchant_name
string | null

The name of the merchant to display on the payment link.

Maximum string length: 100
Example:

"Gr4vy"

​
merchant_url
string | null

The URL of the merchant to display on the payment link.

Example:

"https://gr4vy.com"

​
merchant_banner_url
string | null

The URL of the merchant banner to display on the payment link.

Example:

"https://gr4vy.com/banner.png"

​
merchant_color
string | null

The color code of the merchant to display on the payment link.

Example:

"#FF0000"

​
merchant_message
string | null

The message to display on the payment link.

Maximum string length: 255
Example:

"Thank you for shopping with us!"

​
merchant_terms_and_conditions_url
string | null

The URL of the merchant terms and conditions to display on the payment link.

Example:

"https://gr4vy.com/terms"

​
merchant_favicon_url
string | null

The URL of the merchant favicon icon.

Example:

"https://gr4vy.com/favicon.png"

​
intent
enum<string> | null
default:authorize

The intent of the payment link.

Available options:
authorize,
capture
Example:

"authorize"

​
return_url
string | null

The URL to redirect the buyer to after payment.

Example:

"https://gr4vy.com/return"

​
cart_items
Cart Item · object[]

An array of cart items that represents the line items of a payment link.

Maximum array length: 249
​
metadata
object

Any additional information about the payment link that you would like to store as key-value pairs. This data is passed to payment service providers that support it.

Example:
{ "key": "value" }
​
payment_source
enum<string> | null

The source of the payment link.

Available options:
ecommerce,
moto,
recurring,
installment,
card_on_file
Example:

"recurring"

Response

Returns the created payment link.

​
id
string<uuid>

The ID of a payment link.

Example:

"8d3fe99b-1422-42e6-bbb3-932d95ae5f79"

​
type
enum<string>

The type of this resource. Is always payment_link.

Available options:
payment_link
Example:

"payment_link"

​
amount
integer

The monetary amount for this payment link, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99.

Example:

1299

​
currency
string

A supported ISO-4217 currency code.

Example:

"USD"

​
created_at
string<date-time>

The date and time when this payment link was created.

Example:

"2022-01-01T12:00:00+00:00"

​
updated_at
string<date-time>

The date and time when this payment link was created.

Example:

"2022-01-01T12:00:00+00:00"

​
expires_at
string<date-time>

The date and time when this payment link expires.

Example:

"2022-01-01T12:00:00+00:00"

​
status
enum<string>
Available options:
active,
completed,
expired,
processing
Example:

"active"

​
external_identifier
string | null

A value that can be used to match the payment link against your own records.

Required string length: 1 - 200
Example:

"payment-link-123"

​
statement_descriptor
Statement descriptor · object

The statement descriptor is the text to be shown on the buyer's statements.

The specific usage of these fields will depend on the capabilities of the underlying PSP and bank. As a typical example, 'name' and 'description' could be concatenated using '* ' as a separator, and then the resulting descriptor would be truncated to 22 characters by the issuing bank.

​
locale
enum<string> | null

The locale used to translate text within the payment link.

Available options:
en,
en-GB,
es,
pt,
pt-BR
Example:

"en"

​
merchant_name
string | null

The name of the merchant to display on the payment link.

Maximum string length: 100
Example:

"Gr4vy"

​
merchant_url
string | null

The URL of the merchant to display on the payment link.

Example:

"https://gr4vy.com"

​
merchant_banner_url
string | null

The URL of the merchant banner to display on the payment link.

Example:

"https://gr4vy.com/banner.png"

​
merchant_color
string | null

The color code of the merchant to display on the payment link.

Example:

"#FF0000"

​
merchant_message
string | null

The message to display on the payment link.

Maximum string length: 255
Example:

"Thank you for shopping with us!"

​
merchant_terms_and_conditions_url
string | null

The URL of the merchant terms and conditions to display on the payment link.

Example:

"https://gr4vy.com/terms"

​
merchant_favicon_url
string | null

The URL of the merchant favicon icon.

Example:

"https://gr4vy.com/favicon.png"

​
country
string | null

The 2-letter ISO code of the country of the transaction. This is used to filter the payment services that is used to process the transaction.

Example:

"US"

​
intent
enum<string> | null

The intent of the payment link.

Available options:
authorize,
capture
Example:

"authorize"

​
return_url
string | null

The URL to redirect the buyer to after payment.

Example:

"https://gr4vy.com/return"

​
cart_items
Cart Item · object[]

An array of cart items that represents the line items of a payment link.

Maximum array length: 249
​
metadata
object

Any additional information about the payment link that you would like to store as key-value pairs. This data is passed to payment service providers that support it.

Example:
{ "key": "value" }
​
payment_source
enum<string> | null

The source of the payment link. Defaults to ecommerce.

Available options:
ecommerce,
moto,
recurring,
installment,
card_on_file
Example:

"recurring"

​
buyer
Buyer (Snapshot) · object

The buyer used for this transaction.

​
shipping_details
Shipping detail · object

Shipping details for the payment link.