List payment links

Payments

Transactions
Buyers
Checkout Sessions
Payment links
Payment options
Payouts
Refunds
Sessions
Settlement records

Instruments

Card schemes
Digital wallets
Gift cards
Payment methods
Payment method definitions

Vault

Account updater
Network tokens
Payment service tokens
Vault Forward
Vault Forward endpoints
Vault Forward authentication

Connections

All services
Payment services
Digital wallets
Anti-fraud services
Gift-card services

Dashboard

Flow
Merchant accounts
Reports
Report executions

Errors

GET

payment-links

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-links \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "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"
        }
      }
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}

This endpoint requires the payment-links.read scope.

Authorizations

Authorization

string

header

required

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

Response

200

application/json

Returns a paginated list of payment links for an account.

A list of payment links.

items

object[]

A list of payment links.

items.id

string

The ID of a payment link.

Example:

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

items.type

enum<string>

The type of this resource. Is always payment_link.

Available options:

payment_link

Example:

"payment_link"

items.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

items.currency

string

A supported ISO-4217 currency code.

Example:

"USD"

items.created_at

string

The date and time when this payment link was created.

Example:

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

items.updated_at

string

The date and time when this payment link was created.

Example:

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

items.expires_at

string

The date and time when this payment link expires.

Example:

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

items.status

enum<string>

Available options:

active,

expired

Example:

"active"

items.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"

items.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.

items.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"

items.merchant_name

string | null

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

Maximum length: 100

Example:

"Gr4vy"

items.merchant_url

string | null

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

Example:

"https://gr4vy.com"

items.merchant_banner_url

string | null

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

Example:

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

items.merchant_color

string | null

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

Example:

"#FF0000"

items.merchant_message

string | null

The message to display on the payment link.

Maximum length: 255

Example:

"Thank you for shopping with us!"

items.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"

items.merchant_favicon_url

string | null

The URL of the merchant favicon icon.

Example:

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

items.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"

items.intent

enum<string> | null

The intent of the payment link.

Available options:

authorize,

capture

Example:

"authorize"

items.return_url

string | null

The URL to redirect the buyer to after payment.

Example:

"https://gr4vy.com/return"

items.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.

items.cart_items.name

string

required

The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.

Maximum length: 255

Example:

"GoPro HERO9 Camcorder"

items.cart_items.quantity

integer

required

The quantity of this item in the cart. This value cannot be negative or zero.

Required range: 1 <= x <= 99999999

Example:

1

items.cart_items.unit_amount

integer

required

The amount for an individual item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99. The amount sent through to the payment processor as unitary amount will be calculated to include the discount and tax values sent as part of this cart item.

Required range: 0 <= x <= 99999999

Example:

37999

items.cart_items.discount_amount

integer | null

default:

The amount discounted for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Please note that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total discount amount for 5 of the cart item.

You might see unexpected failed transactions if the discount_amount can not be equally divided by the quantity value. This is due to the fact that some payment services require this amount to be specified per unit.

In this situation we recommend splitting this item into separate items, each with their own specific discount.

Required range: 0 <= x <= 99999999

Example:

0

items.cart_items.tax_amount

integer | null

default:

The tax amount for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Please not that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total tax amount for 5 of the cart item.

You might see unexpected failed transactions if the tax_amount can not be equally divided by the quantity value. This is due to the fact that some payment services require this amount to be specified per unit.

In this situation we recommend splitting this item into separate items, each with their own specific tax amount.

Required range: 0 <= x <= 99999999

Example:

0

items.cart_items.external_identifier

string | null

An external identifier for the cart item. This can be set to any value and is not sent to the payment service.

Maximum length: 200

Example:

"item-789123"

items.cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

Example:

"sku-789123"

items.cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

Example:

"https://example.com/items/gopro"

items.cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

Example:

"https://example.com/images/items/gopro.png"

items.cart_items.categories

string[] | null

A list of strings containing product categories for the item. Max length per item: 50.

items.cart_items.product_type

enum<string> | null

The product type of the cart item.

Available options:

physical,

discount,

shipping_fee,

sales_tax,

digital,

gift_card,

store_credit,

surcharge

Example:

"physical"

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

items.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"

items.buyer

object

The buyer used for this transaction.

items.buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

Example:

"buyer"

items.buyer.id

string | null

The unique Gr4vy ID for this buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

items.buyer.billing_details

object

The billing details associated with the buyer, which include the address and tax ID.

items.buyer.billing_details.type

enum<string>

The type of this resource. Is always billing-details.

Available options:

billing-details

Example:

"billing-details"

items.buyer.billing_details.first_name

string | null

The first name(s) or given name of the buyer.

Required string length: 1 - 255

Example:

"John"

items.buyer.billing_details.last_name

string | null

The last name, or family name, of the buyer.

Required string length: 1 - 255

Example:

"Lunn"

items.buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

items.buyer.billing_details.phone_number

string | null

The phone number of the buyer. This number is formatted according to the E164 number standard.

Required string length: 1 - 50

Example:

"+1234567890"

items.buyer.billing_details.address

object

The billing address of the buyer.

items.buyer.billing_details.tax_id

object

The tax information associated with the billing details.

items.buyer.display_name

string | null

A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.

Required string length: 1 - 200

Example:

"John L."

items.buyer.external_identifier

string | null

An external identifier that can be used to match the buyer against your own records.

Required string length: 1 - 200

Example:

"user-789123"

items.buyer.account_number

string | null

The source account number to perform an account funding transaction.

Required string length: 1 - 255

Example:

"1234567"

items.shipping_details

object

Shipping details for the payment link.

items.shipping_details.type

enum<string>

The type of this resource. Is always shipping-details.

Available options:

shipping-details

Example:

"shipping-details"

items.shipping_details.id

string

The unique ID for a buyer's shipping detail.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

items.shipping_details.buyer_id

string

The unique ID for a buyer.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

items.shipping_details.first_name

string | null

The first name(s) or given name of the buyer.

Required string length: 1 - 255

Example:

"John"

items.shipping_details.last_name

string | null

The last name, or family name, of the buyer.

Required string length: 1 - 255

Example:

"Lunn"

items.shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

items.shipping_details.phone_number

string | null

The phone number of the buyer. This number is formatted according to the E164 number standard.

Required string length: 1 - 50

Example:

"+1234567890"

items.shipping_details.address

object

The physical shipping address associated to this buyer.

limit

integer

default:

The limit applied to request. This represents the number of items that are at maximum returned by this request.

Required range: 1 <= x <= 100

Example:

1

next_cursor

string | null

The cursor that represents the next page of results. Use the cursor query parameter to fetch this page of items.

Required string length: 1 - 1000

Example:

"ZXhhbXBsZTE"

previous_cursor

string | null

The cursor that represents the next page of results. Use the cursor query parameter to fetch this page of items.

Required string length: 1 - 1000

Example:

null

Was this page helpful?

Update fields for checkout session Create payment link

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/payment-links \
  --header 'Authorization: Bearer <token>'

{
  "items": [
    {
      "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"
        }
      }
    }
  ],
  "limit": 1,
  "next_cursor": "ZXhhbXBsZTE",
  "previous_cursor": null
}