Create payment link

Payments

Instruments

Vault

Connections

Other

Errors

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"
}'

{
  "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",
      "seller_country": "US"
    }
  ],
  "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.

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

Example:

"user-789123"

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

buyer.billing_details

object

The optional billing details for the a buyer.

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:

"Lunn"

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

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

Example:

"+1234567890"

buyer.billing_details.address

object

The billing address for the buyer.

buyer.billing_details.tax_id

object

The tax ID information associated with the billing details.

buyer.shipping_details

object

The optional shipping details for the buyer.

buyer.shipping_details.type

enum<string>

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

Available options:

shipping-details

Example:

"shipping-details"

buyer.shipping_details.id

string

The unique ID for a buyer's shipping detail.

Example:

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

buyer.shipping_details.buyer_id

string

The unique ID for a buyer.

Example:

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

buyer.shipping_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

buyer.shipping_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Lunn"

buyer.shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

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

Example:

"+1234567890"

buyer.shipping_details.address

object

The physical shipping address associated to this buyer.

buyer.account_number

string | null

The source account number to perform an account funding transaction.

Required string length: 1 - 255

Example:

"1234567"

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.

connection_options.cybersource-card

object | null

Additional options for Cybersource payment gateway.

connection_options.cybersource-card.meta_key_merchant_id

string | null

An override for the merchant ID configured for the connector, used in combination with meta keys.

connection_options.cybersource-card.merchant_defined_information

object

This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1".

Example:

{
  "1": "John Doe",
  "2": "trusted",
  "99": "recurring"
}

connection_options.cybersource-card.ship_to_method

string | null

Shipping method for the order.

connection_options.cybersource-kcp

object | null

Additional options for Cybersource KCP APM.

connection_options.cybersource-kcp.meta_key_merchant_id

string | null

An override for the merchant ID configured for the connector, used in combination with meta keys.

connection_options.cybersource-kcp.merchant_defined_information

object

This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1".

Example:

{
  "1": "John Doe",
  "2": "trusted",
  "99": "recurring"
}

connection_options.cybersource-kcp.ship_to_method

string | null

Shipping method for the order.

connection_options.cybersource-ideal

object | null

Additional options for Cybersource iDeal APM.

connection_options.cybersource-ideal.meta_key_merchant_id

string | null

An override for the merchant ID configured for the connector, used in combination with meta keys.

connection_options.cybersource-ideal.merchant_defined_information

object

This is a key-value object for merchant defined information. Each key needs to be a numeric string identifying the MDI field to set. For example, for field 1 set the key to "1".

Example:

{
  "1": "John Doe",
  "2": "trusted",
  "99": "recurring"
}

connection_options.cybersource-ideal.ship_to_method

string | null

Shipping method for the order.

connection_options.cybersource-anti-fraud

object | null

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

connection_options.cybersource-anti-fraud.meta_key_merchant_id

string | null

An override for the merchant ID configured for the connector, used in combination with meta keys.

connection_options.cybersource-anti-fraud.merchant_defined_data

object

This is a key-value object for merchant defined data. Each key needs to be a numeric string identifying the MDD field to set. For example, for field 1 set the key to "1".

Please avoid fields "31", "48", "50"-"56" and "63"-"76" as these are auto-populated based on the transaction profile.

Example:

{
  "1": "John Doe",
  "2": "trusted",
  "99": "recurring"
}

connection_options.cybersource-anti-fraud.shipping_method

string | null

Shipping method for the order.

connection_options.givingblock-givingblock

object | null

Additional options for Giving Block connector.

connection_options.forter-anti-fraud

object | null

Additional options for Forter (anti-fraud).

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

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.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.adyen-card

object | null

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

connection_options.adyen-card.additionalData

object

A key-value object representing additional data to be passed to Adyen.

Example:

{
  "riskdata.operatorCode": "operatorCode,",
  "riskdata.operatorCountry": "operatorCountry"
}

connection_options.adyen-card.autoRescue

boolean

default:false

Enabled Adyen's auto-rescue feature.

connection_options.adyen-card.maxDaysToRescue

integer | null

Defines the number of days to auto-retry a payment for if autoRescue is enabled.

connection_options.adyen-card.autoRescueScenario

string | null

Defines the Adyen auto-rescue test scenario to invoke.

connection_options.adyen-sepa

object | null

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

connection_options.paypal-paypal

object | null

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

connection_options.paypal-paypal.additional_data

object[]

An array with key-value objects representing additional data to be passed to PayPal.

Example:

[{ "key": "test", "value": "abc" }]

connection_options.paypal-paypalpaylater

object | null

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

connection_options.paypal-paypalpaylater.additional_data

object[]

An array with key-value objects representing additional data to be passed to PayPal.

Example:

[{ "key": "test", "value": "abc" }]

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.

connection_options.fiserv-card

object | null

Additional options for Fiserv IPG payment gateway.

connection_options.latitude-latitude

object | null

Additional options to be passed through to Latitude/Gem when processing transactions.

connection_options.latitude-latitudeds

object | null

Additional options to be passed through to Latitude/Gem when processing transactions.

connection_options.gem-gem

object | null

Additional options to be passed through to Latitude/Gem when processing transactions.

connection_options.gem-gemds

object | null

Additional options to be passed through to Latitude/Gem when processing transactions.

connection_options.nuvei-card

object | null

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

connection_options.travelhub-card

object | null

Additional options to be passed through to Worldline Travelhub when processing transactions.

connection_options.travelhub-card.customData

object[]

An array with name-value objects representing additional data to be passed to Worldline Travelhub.

Example:

[
  {
    "name": "fraud_data_name1",
    "value": "aaa"
  }
]

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.

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"

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

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

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.

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

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.

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

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"

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

Example:

"sku-789123"

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

Example:

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

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"

cart_items.categories

string[] | null

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

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 country code of the seller of the item. For some connectors, if this country code does not match the country then the transaction will be marked to Visa as a foreign seller transaction to meet Marketplace reporting requirements.

Example:

"US"

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.

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,

completed,

expired,

processing

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.

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.

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.

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"

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

cart_items.unit_amount

integer

required

Required range: 0 <= x <= 99999999

Example:

37999

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.

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

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.

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

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.

Maximum length: 200

Example:

"item-789123"

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

Example:

"sku-789123"

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

Example:

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

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"

cart_items.categories

string[] | null

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

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

Example:

"US"

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.

buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

Example:

"buyer"

buyer.id

string | null

The unique Gr4vy ID for this buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

buyer.billing_details

object

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

buyer.billing_details.type

enum<string>

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

Available options:

billing-details

Example:

"billing-details"

buyer.billing_details.first_name

string | null

The first name(s) or given name of 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:

"Lunn"

buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

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"

buyer.billing_details.address

object

The billing address of the buyer.

buyer.billing_details.tax_id

object

The tax 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

Example:

"John L."

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"

buyer.account_number

string | null

The source account number to perform an account funding transaction.

Required string length: 1 - 255

Example:

"1234567"

shipping_details

object

Shipping details for the payment link.

shipping_details.type

enum<string>

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

Available options:

shipping-details

Example:

"shipping-details"

shipping_details.id

string

The unique ID for a buyer's shipping detail.

Example:

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

shipping_details.buyer_id

string

The unique ID for a buyer.

Example:

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

shipping_details.first_name

string | null

The first name(s) or given name of 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:

"Lunn"

shipping_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

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"

shipping_details.address

object

The physical shipping address associated to this buyer.

List payment links Get payment link

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"
}'

{
  "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",
      "seller_country": "US"
    }
  ],
  "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"
    }
  }
}