Skip to main content
POST
C#
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.

Headers

x-gr4vy-merchant-account-id
string

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

Example:

"default"

Body

application/json

The payment link to create

amount
integer
required

The amount for the payment link.

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

1299

country
string
required

The country code for the payment link.

Pattern: ^[A-Z]{2}$
Examples:

"DE"

"GB"

"US"

currency
string
required

The currency code for the payment link.

Pattern: ^[A-Z]{3}$
Examples:

"EUR"

"GBP"

"USD"

buyer
GuestBuyer · object | null

The guest buyer for the payment link.

expires_at
string<date-time> | null

The expiration date and time for the payment link.

Example:

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

connection_options
TransactionConnectionOptions · object | null

Connection options for the payment link.

external_identifier
string | null

The merchant reference for the payment link.

Required string length: 1 - 200
Example:

"external-12345"

statement_descriptor
StatementDescriptor · object | null

The statement descriptor for the payment link.

locale
string | null

The locale for the payment link.

Required string length: 1 - 50
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<color> | null

The merchant's brand color.

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"

intent
string
default:authorize

The transaction intent for the payment link.

Examples:

"authorize"

"capture"

return_url
string | null

The return URL after payment completion.

Example:

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

cart_items
CartItem · object[] | null

The cart items for the payment link.

metadata
Metadata · object | null

Arbitrary metadata for the payment link.

Example:
payment_source
string
default:ecommerce

The payment source for the payment link.

Example:

"ecommerce"

store
boolean
default:false

Whether to store the payment method for future use.

Example:

true

buyer_id
string<uuid> | null

The ID of the buyer to associate the payment method with. Note: When buyer_id is provided, the payment link should be treated as a secret as it will allow the user to manage payment methods for the associated buyer.

Example:

"a1b2c3d4-5678-90ab-cdef-1234567890ab"

installment_count
integer | null

The number of installments a buyer is required to make.

Required range: 1 <= x <= 100

Response

Successful Response

id
string<uuid>
required

The unique identifier for the payment link.

Example:

"a1b2c3d4-5678-90ab-cdef-1234567890ab"

url
string
required

The URL for the payment link.

Example:

"https://example.com/link/a1b2c3d4-5678-90ab-cdef-1234567890ab"

amount
integer
required

The amount for the payment link.

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

1299

country
string
required

The country code for the payment link.

Pattern: ^[A-Z]{2}$
Examples:

"DE"

"GB"

"US"

currency
string
required

The currency code for the payment link.

Pattern: ^[A-Z]{3}$
Examples:

"EUR"

"GBP"

"USD"

intent
string
required

The transaction intent for the payment link.

Examples:

"authorize"

"capture"

cart_items
CartItem · object[] | null
required

The cart items for the payment link.

Example:
payment_source
string
required

The payment source for the payment link.

Example:

"ecommerce"

created_at
string<date-time>
required

The date and time the payment link was created.

Example:

"2024-05-30T12:34:56.000Z"

updated_at
string<date-time>
required

The date and time the payment link was last updated.

Example:

"2024-05-30T13:00:00.000Z"

status
string
required

The status of the payment link.

Examples:

"active"

"expired"

"completed"

type
string
default:payment-link

Always payment-link.

Allowed value: "payment-link"
Example:

"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 | null

The statement descriptor for the payment link.

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 | null

Arbitrary metadata for the payment link.

Example:
buyer
TransactionBuyer · object | null

The buyer associated with the payment link.

shipping_details
ShippingDetails · object | null

The shipping details for the payment link.

connection_options
Connection Options · object | null

The connection options for the payment link.

store
boolean
default:false

Whether the payment method was stored.

buyer_id
string<uuid> | null

The ID of the buyer to associate with the stored payment method.

Example:

"a1b2c3d4-5678-90ab-cdef-1234567890ab"

installment_count
integer | null

The number of installments a buyer is required to make.

Required range: 1 <= x <= 100