New payment link

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

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.

currency

string

required

The ISO-4217 currency code for the payment.

buyer

object

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

buyer.billing_details

object

The optional billing details for the a buyer.

buyer.billing_details.address

object

The billing address for the buyer.

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.phone_number

string | null

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

Required string length: 1 - 50

buyer.billing_details.tax_id

object

The tax ID information associated with the billing details.

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

buyer.external_identifier

string | null

An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers.

Required string length: 1 - 200

buyer.shipping_details

object

The optional shipping details for the buyer.

buyer.shipping_details.address

object

The physical shipping address associated to this buyer.

buyer.shipping_details.buyer_id

string

The unique ID for a buyer.

buyer.shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

buyer.shipping_details.first_name

string | null

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

Required string length: 1 - 255

buyer.shipping_details.id

string

The unique ID for a buyer's shipping detail.

buyer.shipping_details.last_name

string | null

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

Required string length: 1 - 255

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

buyer.shipping_details.type

enum<string>

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

Available options:

shipping-details

cart_items

object[]

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

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

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

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

string[] | null

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

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

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

cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

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

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

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

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.

connection_options.adyen-card

object | null

Additional options to be passed through to Adyen when processing card transactions.

connection_options.adyen-sepa

object | null

Additional options to be passed through to Adyen when processing SEPA transactions.

connection_options.cybersource-anti-fraud

object | null

Additional options for Cybersource Decision Manager (anti-fraud).

connection_options.cybersource-card

object | null

Additional options for Cybersource payment gateway.

connection_options.cybersource-ideal

object | null

Additional options for Cybersource iDeal APM.

connection_options.cybersource-kcp

object | null

Additional options for Cybersource KCP APM.

connection_options.fiserv-card

object | null

Additional options for Fiserv IPG payment gateway.

connection_options.forter-anti-fraud

object | null

Additional options for Forter (anti-fraud).

connection_options.forter-anti-fraud.cart_items

object[]

A list of Forter cart item objects. These will be merged into the cart_items passed to the transaction. Every cart item here will be merged with a cart item on the transaction with the same index.

Together, these will augment the cartItems values sent to the Forter validation API.

connection_options.forter-anti-fraud.cart_items.basic_item_data

object

General data regarding item such as name, price, etc.

connection_options.forter-anti-fraud.cart_items.beneficiaries

object[]

List of all entities receiving or using the purchased cart item.

connection_options.forter-anti-fraud.cart_items.delivery_details

object

General data regarding item such as name, price, etc.

connection_options.forter-anti-fraud.delivery_method

string | null

Value to populate the deliveryMethod field in primaryDeliveryDetails.

Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc.

connection_options.forter-anti-fraud.delivery_type

enum<string> | null

Value to populate the deliveryType field in primaryDeliveryDetails.

Represents the type of delivery. This can be set to PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.), or HYBRID for others.

Available options:

PHYSICAL,

DIGITAL,

HYBRID

connection_options.forter-anti-fraud.is_guest_buyer

boolean

default:

false

Defines if this is a guest check-out. This will redact the accountId and created fields from the accountOwner details sent to Forter.

connection_options.forter-anti-fraud.total_discount

object | null

The totalDiscount object that's sent to Forter's validation API. It represents the discount that was given to the customer.

connection_options.givingblock-givingblock

object | null

Additional options for Giving Block connector.

connection_options.paypal-paypal

object | null

Additional options to be passed through to PayPal when processing transactions.

connection_options.paypal-paypalpaylater

object | null

Additional options to be passed through to PayPal when processing transactions.

connection_options.powertranz-card

object | null

Additional options to be passed through to Powertranz when processing transactions.

connection_options.stripe-card

object | null

Additional options to be passed through to Stripe when processing transactions.

expires_at

string | null

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

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

intent

enum<string> | null

default:

authorize

The intent of the payment link.

Available options:

authorize,

capture

merchant_banner_url

string | null

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

merchant_color

string | null

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

merchant_message

string | null

The message to display on the payment link.

Maximum length: 255

merchant_name

string | null

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

Maximum length: 100

merchant_terms_and_conditions_url

string | null

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

merchant_url

string | null

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

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.

payment_source

enum<string> | null

The source of the payment link.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

return_url

string | null

The URL to redirect the buyer to after payment.

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.

Response

201 - application/json

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.

buyer

object

The buyer used for this transaction.

buyer.billing_details

object

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

buyer.billing_details.address

object

The billing address of the buyer.

buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

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

buyer.billing_details.tax_id

object

The tax information associated with the billing details.

buyer.billing_details.type

enum<string>

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

Available options:

billing-details

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

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

buyer.id

string | null

The unique Gr4vy ID for this buyer.

buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

cart_items

object[]

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

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

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

cart_items.unit_amount

integer

required

Required range: 0 < x < 99999999

cart_items.categories

string[] | null

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

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.

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

Required range: 0 < x < 99999999

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

cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

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

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

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.

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

Required range: 0 < x < 99999999

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.

created_at

string

The date and time when this payment link was created.

currency

string

A supported ISO-4217 currency code.

expires_at

string

The date and time when this payment link expires.

external_identifier

string | null

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

Required string length: 1 - 200

string

The ID of a payment link.

intent

enum<string> | null

The intent of the payment link.

Available options:

authorize,

capture

merchant_banner_url

string | null

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

merchant_color

string | null

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

merchant_message

string | null

The message to display on the payment link.

Maximum length: 255

merchant_name

string | null

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

Maximum length: 100

merchant_terms_and_conditions_url

string | null

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

merchant_url

string | null

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

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.

payment_source

enum<string> | null

The source of the payment link. Defaults to ecommerce.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

return_url

string | null

The URL to redirect the buyer to after payment.

shipping_details

object

Shipping details for the payment link.

shipping_details.address

object

The physical shipping address associated to this buyer.

shipping_details.buyer_id

string

The unique ID for a buyer.

shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

shipping_details.first_name

string | null

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

Required string length: 1 - 255

shipping_details.id

string

The unique ID for a buyer's shipping detail.

shipping_details.last_name

string | null

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

Required string length: 1 - 255

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

shipping_details.type

enum<string>

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

Available options:

shipping-details

statement_descriptor

object

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

status

enum<string>

Available options:

active,

expired

type

enum<string>

The type of this resource. Is always payment_link.

Available options:

payment_link

updated_at

string

The date and time when this payment link was created.

Payments

Instruments

Vault

Connections

Dashboard

Errors

New payment link

Authorizations

Body

Response