Get payment link

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.

Headers

x-gr4vy-merchant-account-id

string | null

The ID of the merchant account to use for this request. The ID of the merchant account to use for this request.

Example:

"default"

Path Parameters

payment_link_id

string<uuid>

required

The unique identifier for the payment link. The unique identifier for the payment link.

Response

Successful Response

string<uuid>

required

The unique identifier for the payment link.

url

string

required

The URL for the payment link.

amount

integer

required

The amount for the payment link.

Required range: 0 <= x <= 99999999

country

string

required

The country code for the payment link.

currency

string

required

The currency code for the payment link.

intent

enum<string>

required

The transaction intent for the payment link.

Available options:

authorize,

capture

cart_items

CartItem · object[] | null

required

The cart items for the payment link.

Show child attributes

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.

Required string length: 1 - 255

cart_items.quantity

integer

required

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

Required range: x <= 99999999

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

cart_items.discount_amount

integer | null

default:0

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.

Required range: 0 <= x <= 99999999

Example:

0

cart_items.tax_amount

integer | null

default:0

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.

Required range: 0 <= x <= 99999999

Example:

0

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.

Required string length: 1 - 200

Example:

"goprohd"

cart_items.sku

string | null

The SKU or product code for the item.

Required string length: 1 - 200

Example:

"GPHD1078"

cart_items.upc

string | null

The UPC for the item.

Required string length: 1 - 50

Example:

"012345678905"

cart_items.product_url

string | null

The product URL for the item.

Example:

"https://example.com/catalog/go-pro-hd"

cart_items.image_url

string | null

The URL for the image of the item.

Example:

"https://example.com/images/go-pro-hd.jpg"

cart_items.categories

string[] | null

A list of strings containing product categories for the item.

Required string length: 1 - 50

Example:

["camera", "travel", "gear"]

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"

cart_items.seller_country

string | null

The seller country of the cart item.

Example:

"US"

cart_items.tax_exempt

boolean | null

Whether the item is exempt of tax.

Example:

false

cart_items.unit_of_measure

string | null

The unit of measure or the unit of measure code.

Required string length: 1 - 50

Example:

"feet"

cart_items.commodity_code

string | null

Item commodity code. Generally a UNSPSC code.

Required string length: 1 - 50

Example:

"43211503"

cart_items.description

string | null

Brief item description.

Required string length: 1 - 255

Example:

"A brief description of an interesting item."

cart_items.duty_amount

integer | null

Item import or export duties represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99

Required range: 0 <= x <= 99999999

Example:

1299

cart_items.shipping_amount

integer | null

Freight/shipping amount represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99

Required range: 0 <= x <= 99999999

Example:

1299

Example:

[
  {
    "amount": { "currency": "USD", "value": 500 },
    "name": "Widget",
    "quantity": 2
  }
]

payment_source

enum<string>

required

The way payment method information made it to this transaction.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

created_at

string<date-time>

required

The date and time the payment link was created.

updated_at

string<date-time>

required

The date and time the payment link was last updated.

status

enum<string>

required

The status of the payment link.

Available options:

active,

completed,

expired,

processing

type

string

default:payment-link

Always payment-link.

Allowed value: "payment-link"

expires_at

string<date-time> | null

The expiration date and time for the payment link.

Example:

"2024-06-01T00:00:00.000Z"

external_identifier

string | null

The merchant reference for the payment link.

Required string length: 1 - 200

Example:

"external-12345"

statement_descriptor

StatementDescriptor · object

The statement descriptor for the payment link.

Show child attributes

statement_descriptor.name

string | null

Reflects your doing business as (DBA) name.

Required string length: 5 - 22

Example:

"ACME"

statement_descriptor.description

string | null

A short description about the purchase.

Required string length: 5 - 22

Example:

"ACME San Jose Electronics"

statement_descriptor.city

string | null

The merchant's city to be displayed in a statement descriptor.

Required string length: 1 - 50

Example:

"San Jose"

statement_descriptor.country

string | null

The 2-letter ISO country code of the merchant to be displayed in a statement descriptor.

Example:

"US"

statement_descriptor.phone_number

string | null

The value in the phone number field of a customer's statement which should be formatted according to the E164 number standard.

Example:

"+1234567890"

statement_descriptor.url

string | null

The merchant's URL to be displayed in a statement descriptor.

Required string length: 1 - 50

Example:

"www.example.com"

statement_descriptor.postal_code

string | null

The merchant's postal code or zip code.

Required string length: 1 - 50

Example:

"94560"

locale

string | null

The locale for the payment link.

Example:

"en"

merchant_name

string | null

The merchant's display name.

Required string length: 1 - 100

Example:

"ACME Inc."

merchant_url

string | null

The merchant's website URL.

Example:

"https://merchant.example.com"

merchant_banner_url

string | null

The merchant's banner image URL.

Example:

"https://merchant.example.com/banner.png"

merchant_color

string | null

The merchant's brand color.

Required string length: 1 - 100

Example:

"#FF5733"

merchant_message

string | null

A message from the merchant.

Required string length: 1 - 255

Example:

"Thank you for your purchase!"

merchant_terms_and_conditions_url

string | null

URL to the merchant's terms and conditions.

Example:

"https://merchant.example.com/terms"

merchant_favicon_url

string | null

URL to the merchant's favicon.

Example:

"https://merchant.example.com/favicon.ico"

return_url

string | null

The return URL after payment completion.

Example:

"https://merchant.example.com/return"

metadata

Metadata · object

Arbitrary metadata for the payment link.

Example:

{ "order_id": "ORD-12345" }

buyer

TransactionBuyer · object

The buyer associated with the payment link.

Show child attributes

buyer.type

string

default:buyer

Always buyer.

Allowed value: "buyer"

buyer.id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

buyer.display_name

string | null

The display name for the buyer.

Required string length: 1 - 200

Example:

"John Doe"

buyer.external_identifier

string | null

The merchant identifier for this buyer.

Required string length: 1 - 200

Example:

"buyer-12345"

buyer.billing_details

BillingDetails · object

The billing name, address, email, and other fields for this buyer.

Show child attributes

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

buyer.billing_details.phone_number

string | null

The phone number for the buyer which should be formatted according to the E164 number standard.

Example:

"+1234567890"

buyer.billing_details.address

Address · object

The billing address for the buyer.

Show child attributes

buyer.billing_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

buyer.billing_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

buyer.billing_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

buyer.billing_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

buyer.billing_details.address.state_code

string | null

The code of state, county, or province for the address in ISO 3166-2 format.

Example:

"US-CA"

buyer.billing_details.address.house_number_or_name

string | null

The house number or name for the address. Not all payment services use this field but some do.

Required string length: 1 - 255

Example:

"10"

buyer.billing_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

buyer.billing_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

buyer.billing_details.address.organization

string | null

The optional name of the company or organisation to add to the address.

Required string length: 1 - 255

Example:

"Gr4vy"

buyer.billing_details.tax_id

TaxId · object

The tax ID information associated with the billing details.

Show child attributes

buyer.billing_details.tax_id.value

string

required

The tax ID for the buyer.

Required string length: 1 - 50

buyer.billing_details.tax_id.kind

enum<string>

required

The kind of tax ID

Available options:

ae.trn,

au.abn,

ar.dni,

ar.cuil,

ar.cuit,

br.cnpj,

br.cpf,

ca.bn,

ca.gst_hst,

ca.pst_bc,

ca.pst_mb,

ca.pst_sk,

ca.qst,

ch.vat,

cl.tin,

co.itin,

co.nit,

es.cif,

eu.vat,

gb.vat,

hk.br,

id.nik,

id.npwp,

in.gst,

in.pan,

jp.cn,

jp.rn,

kr.brn,

li.uid,

mx.curp,

mx.rfc,

my.frp,

my.itn,

my.nric,

my.sst,

no.vat,

nz.gst,

pe.ruc,

ph.tin,

ru.inn,

ru.kpp,

sa.vat,

sg.gst,

sg.uen,

th.id,

th.vat,

tw.vat,

us.ein,

za.vat,

bo.ci,

uy.rut,

uy.ci

buyer.account_number

string | null

The buyer account number.

Required string length: 1 - 200

shipping_details

ShippingDetails · object

The shipping details for the payment link.

Show child attributes

shipping_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

shipping_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

shipping_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

shipping_details.phone_number

string | null

The phone number for the buyer which should be formatted according to the E164 number standard.

Example:

"+1234567890"

shipping_details.address

Address · object

The billing address for the buyer.

Show child attributes

shipping_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

shipping_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

shipping_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

shipping_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

shipping_details.address.state_code

string | null

The code of state, county, or province for the address in ISO 3166-2 format.

Example:

"US-CA"

shipping_details.address.house_number_or_name

string | null

The house number or name for the address. Not all payment services use this field but some do.

Required string length: 1 - 255

Example:

"10"

shipping_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

shipping_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

shipping_details.address.organization

string | null

The optional name of the company or organisation to add to the address.

Required string length: 1 - 255

Example:

"Gr4vy"

shipping_details.id

string<uuid> | null

The ID for the shipping details.

Example:

"bf8c36ad-02d9-4904-b0f9-a230b149e341"

shipping_details.buyer_id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

shipping_details.type

string

default:shipping-details

Always shipping-details.

Allowed value: "shipping-details"

connection_options

Connection Options · object

The connection options for the payment link.

Show child attributes

connection_options.{key}

object

Introduction

Transactions

Buyers

Checkout Sessions

Payment links

Payment options

Payouts

Refunds

Sessions

Settlement records

Disputes

Instruments

Vault

Connections

Errors

Other

Get payment link

Authorizations

Headers

Path Parameters

Response