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
Dashboard
- Flow
- Reports
- Report executions
Create payment link
Creates a new 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",
"buyer": {
"external_identifier": "user-789123",
"display_name": "John L.",
"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"
}
},
"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"
}
},
"account_number": "1234567"
},
"expires_at": "2022-01-01T12:00:00+00:00",
"connection_options": {
"cybersource-card": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-kcp": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-ideal": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-anti-fraud": {
"meta_key_merchant_id": "<string>",
"merchant_defined_data": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"shipping_method": "<string>"
},
"givingblock-givingblock": {
"defaultCryptocurrency": "ETH"
},
"forter-anti-fraud": {
"delivery_type": "PHYSICAL",
"delivery_method": "<string>",
"is_guest_buyer": false,
"cart_items": [
{
"basic_item_data": {
"type": "TANGIBLE"
},
"delivery_details": {
"delivery_type": "PHYSICAL",
"delivery_method": "USPS - Ground Mail"
},
"beneficiaries": [
{
"personal_details": {
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
},
"address": {
"country": "US",
"address1": "235 Montgomery st.",
"address2": "Ste. 1110",
"zip": "94104",
"region": "CA",
"company": "Generic Corp. ltd.",
"city": "San Francisco"
},
"phone": [
{
"phone": "15557654321"
}
],
"comments": {
"user_comments_to_merchant": "Please wrap with care!!",
"message_to_beneficiary": "Enjoy the gift John!",
"merchant_comments": "Shipping delayed"
}
}
]
}
],
"total_discount": {
"coupon_code_used": "FATHERSDAY2015",
"discount_type": "COUPON",
"coupon_discount_amount": {
"amount_usd": "99.95",
"amount_local_currency": "105.55",
"currency": "CAD"
},
"coupon_discount_percent": "20%"
}
},
"adyen-card": {
"additionalData": {
"riskdata.operatorCode": "operatorCode,",
"riskdata.operatorCountry": "operatorCountry"
},
"autoRescue": false,
"maxDaysToRescue": null,
"autoRescueScenario": null
},
"adyen-sepa": {
"autoRescue": false,
"maxDaysToRescue": null,
"autoRescueSepaScenario": null,
"ownerName": null
},
"paypal-paypal": {
"additional_data": [
{
"key": "test",
"value": "abc"
}
]
},
"paypal-paypalpaylater": {
"additional_data": [
{
"key": "test",
"value": "abc"
}
]
},
"powertranz-card": {
"skipThreeDSecure": false
},
"stripe-card": {
"error_on_requires_action": false,
"stripe_connect": {
"stripe_account": "<string>",
"application_fee_amount": 123,
"on_behalf_of": "<string>"
}
},
"fiserv-card": {
"installmentOptions": {
"numberOfInstallments": 123,
"installmentsInterest": true,
"installmentDelayMonths": 123,
"merchantAdviceCodeSupported": true
}
}
},
"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",
"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"
}'{
"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"
}
}
}This endpoint requires the payment-links.write scope.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for creating a new payment link.
The amount to request payment for.
1 < x < 99999999The ISO-4217 currency code for the payment.
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.
Guest buyer details provided inline. No buyer resource will be created on Gr4vy when used.
An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers.
1 - 200A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200The optional billing details for the a buyer.
The first name(s) or given name for the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address for the buyer.
1 - 320The phone number for the buyer which should be formatted according to the E164 number standard.
1 - 50The billing address for the buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The first line of the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The tax ID information associated with the billing details.
The tax ID for the buyer.
1 - 50The kind of tax ID.
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, es.cif, eu.vat, gb.vat, hk.br, id.nik, id.npwp, in.gst, jp.cn, jp.rn, kr.brn, li.uid, mx.curp, my.frp, my.itn, my.nric, my.sst, no.vat, nz.gst, ph.tin, ru.inn, ru.kpp, sa.vat, sg.gst, sg.uen, th.id, th.vat, tw.vat, us.ein, za.vat The optional shipping details for the buyer.
The type of this resource. Is always shipping-details.
shipping-details The unique ID for a buyer's shipping detail.
The unique ID for a buyer.
The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The physical shipping address associated to this buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The source account number to perform an account funding transaction.
1 - 255The date and time when this payment link expires. Defaults to 24 hours from creation.
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.
Additional options for Cybersource payment gateway.
An override for the merchant ID configured for the connector, used in combination with meta keys.
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".
Shipping method for the order.
Additional options for Cybersource KCP APM.
An override for the merchant ID configured for the connector, used in combination with meta keys.
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".
Shipping method for the order.
Additional options for Cybersource iDeal APM.
An override for the merchant ID configured for the connector, used in combination with meta keys.
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".
Shipping method for the order.
Additional options for Cybersource Decision Manager (anti-fraud).
An override for the merchant ID configured for the connector, used in combination with meta keys.
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.
Shipping method for the order.
Additional options for Giving Block connector.
The default crypto currency to display on the hosted page presented by The Giving Block.
Additional options for Forter (anti-fraud).
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.
PHYSICAL, DIGITAL, HYBRID Value to populate the deliveryMethod field in primaryDeliveryDetails.
Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc.
Defines if this is a guest check-out. This will redact the accountId and
created fields from the accountOwner details sent to Forter.
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.
General data regarding item such as name, price, etc.
Tangible if physical item, non-tangible if any other product.
TANGIBLE, NON_TANGIBLE General data regarding item such as name, price, etc.
Value to populate the deliveryType field for this cart item. This overrides
the type set at the wider level.
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.
PHYSICAL, DIGITAL, HYBRID Value to populate the deliveryMethod field for this cart item. This overrides
the method set at the wider level.
Represents the delivery method chosen by customer such as postal service, email, in game transfer, etc.
List of all entities receiving or using the purchased cart item.
Personal details are those which contribute to building up a picture of the person as an individual, such as name, title, etc.
Address details for the beneficiary.
List of all phone numbers for the beneficiary.
Comments to merchant or beneficiary written by customer.
The totalDiscount object that's sent to Forter's validation API.
It represents the discount that was given to the customer.
The discount type.
250The coupon code used.
150A monetary amount in USD or local currency.
Transaction amount in USD.
12Transaction amount in currency chosen by the buyer.
20Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code.
3Coupon discount percentage.
Additional options to be passed through to Adyen when processing card transactions.
A key-value object representing additional data to be passed to Adyen.
Enabled Adyen's auto-rescue feature.
Defines the number of days to auto-retry a payment for if autoRescue
is enabled.
Defines the Adyen auto-rescue test scenario to invoke.
Additional options to be passed through to Adyen when processing SEPA transactions.
Enabled Adyen's auto-rescue feature.
Defines the number of days to auto-retry a payment for if autoRescue
is enabled.
Defines the Adyen auto-rescue test scenario to invoke.
Defines the type of chargeback that you want to simulate.
Additional options to be passed through to PayPal when processing transactions.
Additional options to be passed through to PayPal when processing transactions.
Additional options to be passed through to Powertranz when processing transactions.
Allows skipping of 3DS. Without this, every transaction will be sent via Powertranz's 3DS server, even though 3DS might not be triggered.
Additional options to be passed through to Stripe when processing transactions.
Defines if Stripe should automatically fail the payment if it requires two-factor authentication from the user.
Stripe Connect configuration options.
The ID of the connected Stripe account to process for.
The application fee to charge when processing for a connected account.
The Stripe account ID that these funds are intended for.
Additional options for Fiserv IPG payment gateway.
Fiserv installment options.
Number of installments for a sale transaction if the customer pays the total amount in multiple transactions.
Indicates whether the installment interest amount has been applied.
The number of months the first installment payment will be delayed.
Indicates if the merchant supports merchant advice code (MAC) in order to receive table 55 code for a declined recurring transaction.
A value that can be used to match the payment link against your own records. This will also be applied to any transaction.
1 - 200The 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.
Reflects your doing business as (DBA) name.
Other validations:
- Contains only Latin characters.
- Contain at least one letter
- Does not contain any of the special characters
< > \ ' " * - Supports:
- Lower case:
a-z - Upper case:
A-Z - Numbers:
0-9 - Spaces:
- Special characters:
. , _ - ? + /.
5 - 22A short description about the purchase.
Other validations:
- Contains only Latin characters.
- Contain at least one letter
- Does not contain any of the special characters
< > \ ' " * - Supports:
- Lower case:
a-z - Upper case:
A-Z - Numbers:
0-9 - Spaces:
- Special characters:
. , _ - ? + /.
5 - 22The merchant's city to be displayed in a statement descriptor.
1 - 13The 2-letter ISO country code of the merchant to be displayed in a statement descriptor.
The value in the phone number field of a customer's statement which should be formatted according to the E164 number standard.
5 - 20The merchant's URL to be displayed in a statement descriptor.
1 - 13The locale used to translate text within the payment link.
en, en-GB, es, pt, pt-BR The name of the merchant to display on the payment link.
100The URL of the merchant to display on the payment link.
The URL of the merchant banner to display on the payment link.
The color code of the merchant to display on the payment link.
The message to display on the payment link.
255The URL of the merchant terms and conditions to display on the payment link.
The URL of the merchant favicon icon.
The intent of the payment link.
authorize, capture The URL to redirect the buyer to after payment.
An array of cart items that represents the line items of a payment link.
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.
255The quantity of this item in the cart. This value cannot be negative or zero.
1 < x < 99999999The 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.
0 < x < 99999999The 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.
0 < x < 99999999The 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.
0 < x < 99999999An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
200The SKU for the item.
200The product URL for the item.
2083The URL for the image of the item.
2083A list of strings containing product categories for the item. Max length per item: 50.
The product type of the cart item.
physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit, surcharge 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.
The source of the payment link.
ecommerce, moto, recurring, installment, card_on_file Response
The ID of a payment link.
The type of this resource. Is always payment_link.
payment_link 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.
A supported ISO-4217 currency code.
The date and time when this payment link was created.
The date and time when this payment link was created.
The date and time when this payment link expires.
active, expired A value that can be used to match the payment link against your own records.
1 - 200The 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.
Reflects your doing business as (DBA) name.
Other validations:
- Contains only Latin characters.
- Contain at least one letter
- Does not contain any of the special characters
< > \ ' " * - Supports:
- Lower case:
a-z - Upper case:
A-Z - Numbers:
0-9 - Spaces:
- Special characters:
. , _ - ? + /.
5 - 22A short description about the purchase.
Other validations:
- Contains only Latin characters.
- Contain at least one letter
- Does not contain any of the special characters
< > \ ' " * - Supports:
- Lower case:
a-z - Upper case:
A-Z - Numbers:
0-9 - Spaces:
- Special characters:
. , _ - ? + /.
5 - 22The merchant's city to be displayed in a statement descriptor.
1 - 13The 2-letter ISO country code of the merchant to be displayed in a statement descriptor.
The value in the phone number field of a customer's statement which should be formatted according to the E164 number standard.
5 - 20The merchant's URL to be displayed in a statement descriptor.
1 - 13The locale used to translate text within the payment link.
en, en-GB, es, pt, pt-BR The name of the merchant to display on the payment link.
100The URL of the merchant to display on the payment link.
The URL of the merchant banner to display on the payment link.
The color code of the merchant to display on the payment link.
The message to display on the payment link.
255The URL of the merchant terms and conditions to display on the payment link.
The URL of the merchant favicon icon.
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.
The intent of the payment link.
authorize, capture The URL to redirect the buyer to after payment.
An array of cart items that represents the line items of a payment link.
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.
255The quantity of this item in the cart. This value cannot be negative or zero.
1 < x < 99999999The 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.
0 < x < 99999999The 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.
0 < x < 99999999The 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.
0 < x < 99999999An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
200The SKU for the item.
200The product URL for the item.
2083The URL for the image of the item.
2083A list of strings containing product categories for the item. Max length per item: 50.
The product type of the cart item.
physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit, surcharge 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.
The source of the payment link. Defaults to ecommerce.
ecommerce, moto, recurring, installment, card_on_file The buyer used for this transaction.
The type of this resource. Is always buyer.
buyer The unique Gr4vy ID for this buyer.
The billing details associated with the buyer, which include the address and tax ID.
The type of this resource. Is always billing-details.
billing-details The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The billing address of the buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The tax information associated with the billing details.
The tax ID for the buyer.
1 - 50The kind of tax ID.
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, es.cif, eu.vat, gb.vat, hk.br, id.nik, id.npwp, in.gst, jp.cn, jp.rn, kr.brn, li.uid, mx.curp, my.frp, my.itn, my.nric, my.sst, no.vat, nz.gst, ph.tin, ru.inn, ru.kpp, sa.vat, sg.gst, sg.uen, th.id, th.vat, tw.vat, us.ein, za.vat A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200An external identifier that can be used to match the buyer against your own records.
1 - 200The source account number to perform an account funding transaction.
1 - 255Shipping details for the payment link.
The type of this resource. Is always shipping-details.
shipping-details The unique ID for a buyer's shipping detail.
The unique ID for a buyer.
The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The physical shipping address associated to this buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255Was this page helpful?
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",
"buyer": {
"external_identifier": "user-789123",
"display_name": "John L.",
"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"
}
},
"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"
}
},
"account_number": "1234567"
},
"expires_at": "2022-01-01T12:00:00+00:00",
"connection_options": {
"cybersource-card": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-kcp": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-ideal": {
"meta_key_merchant_id": "<string>",
"merchant_defined_information": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"ship_to_method": "<string>"
},
"cybersource-anti-fraud": {
"meta_key_merchant_id": "<string>",
"merchant_defined_data": {
"1": "John Doe",
"2": "trusted",
"99": "recurring"
},
"shipping_method": "<string>"
},
"givingblock-givingblock": {
"defaultCryptocurrency": "ETH"
},
"forter-anti-fraud": {
"delivery_type": "PHYSICAL",
"delivery_method": "<string>",
"is_guest_buyer": false,
"cart_items": [
{
"basic_item_data": {
"type": "TANGIBLE"
},
"delivery_details": {
"delivery_type": "PHYSICAL",
"delivery_method": "USPS - Ground Mail"
},
"beneficiaries": [
{
"personal_details": {
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
},
"address": {
"country": "US",
"address1": "235 Montgomery st.",
"address2": "Ste. 1110",
"zip": "94104",
"region": "CA",
"company": "Generic Corp. ltd.",
"city": "San Francisco"
},
"phone": [
{
"phone": "15557654321"
}
],
"comments": {
"user_comments_to_merchant": "Please wrap with care!!",
"message_to_beneficiary": "Enjoy the gift John!",
"merchant_comments": "Shipping delayed"
}
}
]
}
],
"total_discount": {
"coupon_code_used": "FATHERSDAY2015",
"discount_type": "COUPON",
"coupon_discount_amount": {
"amount_usd": "99.95",
"amount_local_currency": "105.55",
"currency": "CAD"
},
"coupon_discount_percent": "20%"
}
},
"adyen-card": {
"additionalData": {
"riskdata.operatorCode": "operatorCode,",
"riskdata.operatorCountry": "operatorCountry"
},
"autoRescue": false,
"maxDaysToRescue": null,
"autoRescueScenario": null
},
"adyen-sepa": {
"autoRescue": false,
"maxDaysToRescue": null,
"autoRescueSepaScenario": null,
"ownerName": null
},
"paypal-paypal": {
"additional_data": [
{
"key": "test",
"value": "abc"
}
]
},
"paypal-paypalpaylater": {
"additional_data": [
{
"key": "test",
"value": "abc"
}
]
},
"powertranz-card": {
"skipThreeDSecure": false
},
"stripe-card": {
"error_on_requires_action": false,
"stripe_connect": {
"stripe_account": "<string>",
"application_fee_amount": 123,
"on_behalf_of": "<string>"
}
},
"fiserv-card": {
"installmentOptions": {
"numberOfInstallments": 123,
"installmentsInterest": true,
"installmentDelayMonths": 123,
"merchantAdviceCodeSupported": true
}
}
},
"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",
"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"
}'{
"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"
}
}
}