POST
/
payment-links
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "country": "US",
  "buyer": {
    "external_identifier": "user-789123",
    "display_name": "John L.",
    "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"
      }
    },
    "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"
      }
    },
    "account_number": "1234567"
  },
  "expires_at": "2022-01-01T12:00:00+00:00",
  "connection_options": {
    "cybersource-card": {
      "meta_key_merchant_id": "<string>",
      "merchant_defined_information": {
        "1": "John Doe",
        "2": "trusted",
        "99": "recurring"
      },
      "ship_to_method": "<string>"
    },
    "cybersource-kcp": {
      "meta_key_merchant_id": "<string>",
      "merchant_defined_information": {
        "1": "John Doe",
        "2": "trusted",
        "99": "recurring"
      },
      "ship_to_method": "<string>"
    },
    "cybersource-ideal": {
      "meta_key_merchant_id": "<string>",
      "merchant_defined_information": {
        "1": "John Doe",
        "2": "trusted",
        "99": "recurring"
      },
      "ship_to_method": "<string>"
    },
    "cybersource-anti-fraud": {
      "meta_key_merchant_id": "<string>",
      "merchant_defined_data": {
        "1": "John Doe",
        "2": "trusted",
        "99": "recurring"
      },
      "shipping_method": "<string>"
    },
    "givingblock-givingblock": {
      "defaultCryptocurrency": "ETH"
    },
    "forter-anti-fraud": {
      "delivery_type": "PHYSICAL",
      "delivery_method": "<string>",
      "is_guest_buyer": false,
      "cart_items": [
        {
          "basic_item_data": {
            "type": "TANGIBLE"
          },
          "delivery_details": {
            "delivery_type": "PHYSICAL",
            "delivery_method": "USPS - Ground Mail"
          },
          "beneficiaries": [
            {
              "personal_details": {
                "first_name": "John",
                "last_name": "Smith",
                "email": "john@example.com"
              },
              "address": {
                "country": "US",
                "address1": "235 Montgomery st.",
                "address2": "Ste. 1110",
                "zip": "94104",
                "region": "CA",
                "company": "Generic Corp. ltd.",
                "city": "San Francisco"
              },
              "phone": [
                {
                  "phone": "15557654321"
                }
              ],
              "comments": {
                "user_comments_to_merchant": "Please wrap with care!!",
                "message_to_beneficiary": "Enjoy the gift John!",
                "merchant_comments": "Shipping delayed"
              }
            }
          ]
        }
      ],
      "total_discount": {
        "coupon_code_used": "FATHERSDAY2015",
        "discount_type": "COUPON",
        "coupon_discount_amount": {
          "amount_usd": "99.95",
          "amount_local_currency": "105.55",
          "currency": "CAD"
        },
        "coupon_discount_percent": "20%"
      }
    },
    "adyen-card": {
      "additionalData": {
        "riskdata.operatorCode": "operatorCode,",
        "riskdata.operatorCountry": "operatorCountry"
      },
      "autoRescue": false,
      "maxDaysToRescue": null,
      "autoRescueScenario": null
    },
    "adyen-sepa": {
      "autoRescue": false,
      "maxDaysToRescue": null,
      "autoRescueSepaScenario": null,
      "ownerName": null
    },
    "paypal-paypal": {
      "additional_data": [
        {
          "key": "test",
          "value": "abc"
        }
      ]
    },
    "paypal-paypalpaylater": {
      "additional_data": [
        {
          "key": "test",
          "value": "abc"
        }
      ]
    },
    "powertranz-card": {
      "skipThreeDSecure": false
    },
    "stripe-card": {
      "error_on_requires_action": false,
      "stripe_connect": {
        "stripe_account": "<string>",
        "application_fee_amount": 123,
        "on_behalf_of": "<string>"
      }
    },
    "fiserv-card": {
      "installmentOptions": {
        "numberOfInstallments": 123,
        "installmentsInterest": true,
        "installmentDelayMonths": 123,
        "merchantAdviceCodeSupported": true
      }
    }
  },
  "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",
  "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"
    }
  ],
  "metadata": {
    "key": "value"
  },
  "payment_source": "recurring"
}'
{
  "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"
    }
  ],
  "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
object

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

​
expires_at
string | 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
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
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 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 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
object[]

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

A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.

If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:

(unit_amount * quantity) - discount_amount + tax_amount

It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.

​
metadata
object | null

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

201
application/json
Returns the created payment link.
​
id
string

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

The date and time when this payment link was created.

Example:

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

​
updated_at
string

The date and time when this payment link was created.

Example:

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

​
expires_at
string

The date and time when this payment link expires.

Example:

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

​
status
enum<string>
Available options:
active,
expired
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
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 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 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
object[]

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

A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.

If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:

(unit_amount * quantity) - discount_amount + tax_amount

It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.

​
metadata
object | null

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
object

The buyer used for this transaction.

​
shipping_details
object

Shipping details for the payment link.

Was this page helpful?

List payment linksGet payment link