Add a 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.

Headers

x-gr4vy-merchant-account-id

string | null

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

country

string

required

The country code for the payment link.

currency

string

required

The currency code for the payment link.

buyer

GuestBuyer · object

The guest buyer for the payment link.

Show child attributes

buyer.display_name

string | null

The display name for the buyer.

Required string length: 1 - 200

Example:

"John Doe"

buyer.external_identifier

string | null

The merchant identifier for this buyer.

Required string length: 1 - 200

Example:

"buyer-12345"

buyer.billing_details

BillingDetails · object

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

Show child attributes

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

buyer.billing_details.phone_number

string | null

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

Example:

"+1234567890"

buyer.billing_details.address

Address · object

The billing address for the buyer.

Show child attributes

buyer.billing_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

buyer.billing_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

buyer.billing_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

buyer.billing_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

buyer.billing_details.address.state_code

string | null

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

Example:

"US-CA"

buyer.billing_details.address.house_number_or_name

string | null

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

Required string length: 1 - 255

Example:

"10"

buyer.billing_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

buyer.billing_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

buyer.billing_details.address.organization

string | null

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

Required string length: 1 - 255

Example:

"Gr4vy"

buyer.billing_details.tax_id

TaxId · object

The tax ID information associated with the billing details.

Show child attributes

buyer.billing_details.tax_id.value

string

required

The tax ID for the buyer.

Required string length: 1 - 50

buyer.billing_details.tax_id.kind

enum<string>

required

The kind of tax ID

Available options:

ae.trn,

au.abn,

ar.dni,

ar.cuil,

ar.cuit,

br.cnpj,

br.cpf,

ca.bn,

ca.gst_hst,

ca.pst_bc,

ca.pst_mb,

ca.pst_sk,

ca.qst,

ch.vat,

cl.tin,

co.itin,

co.nit,

es.cif,

eu.vat,

gb.vat,

hk.br,

id.nik,

id.npwp,

in.gst,

in.pan,

jp.cn,

jp.rn,

kr.brn,

li.uid,

mx.curp,

mx.rfc,

my.frp,

my.itn,

my.nric,

my.sst,

no.vat,

nz.gst,

pe.ruc,

ph.tin,

ru.inn,

ru.kpp,

sa.vat,

sg.gst,

sg.uen,

th.id,

th.vat,

tw.vat,

us.ein,

za.vat,

bo.ci,

uy.rut,

uy.ci

buyer.account_number

string | null

The buyer account number

Required string length: 1 - 200

buyer.shipping_details

ShippingDetailsCreate · object

The optional shipping details for this buyer.

Show child attributes

buyer.shipping_details.first_name

string | null

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

"Doe"

buyer.shipping_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

buyer.shipping_details.phone_number

string | null

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

Example:

"+1234567890"

buyer.shipping_details.address

Address · object

The billing address for the buyer.

Show child attributes

buyer.shipping_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

buyer.shipping_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

buyer.shipping_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

buyer.shipping_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

buyer.shipping_details.address.state_code

string | null

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

Example:

"US-CA"

buyer.shipping_details.address.house_number_or_name

string | null

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

Required string length: 1 - 255

Example:

"10"

buyer.shipping_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

buyer.shipping_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

buyer.shipping_details.address.organization

string | null

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

Required string length: 1 - 255

Example:

"Gr4vy"

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

Connection options for the payment link.

Show child attributes

connection_options.account-updater

AccountUpdaterOptions · object

Custom options to be passed to the account-updater connector, allowing for simulating different account updater responses.

Show child attributes

connection_options.account-updater.response_code

string | null

The type of response to simulate.

Allowed value: "updated"

Example:

"updated"

connection_options.account-updater.account_number

string | null

When the response_code is set to updated, the payment method's account number will be updated to this value.

Required string length: 12 - 18

Example:

"4242424242424242"

connection_options.account-updater.expiration_month

string | null

When the response_code is set to updated, the payment method's expiration month will be updated to this value.

Required string length: 2

Example:

"12"

connection_options.account-updater.expiration_year

string | null

When the response_code is set to updated, the payment method's expiration year will be updated to this value.

Required string length: 4

Example:

"2030"

connection_options.account-updater.error_code

string | null

The type of error code to simulate.

Example:

"error"

connection_options.adyen-afterpay

AdyenOptions · object

Custom options to be passed to the adyen-afterpay connector.

Show child attributes

connection_options.adyen-afterpay.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-afterpay.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-alipay

AdyenOptions · object

Custom options to be passed to the adyen-alipay connector.

Show child attributes

connection_options.adyen-alipay.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-alipay.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-card

AdyenCardOptions · object

Custom options to be passed to the adyen-card connector.

Show child attributes

connection_options.adyen-card.autoRescue

boolean | null

Set to true to enable Auto Rescue for a transaction. Use the maxDaysToRescue to specify a rescue window.

Example:

true

connection_options.adyen-card.maxDaysToRescue

integer | null

The rescue window for a transaction, in days, when autoRescue is set to true. You can specify a value between 1 and 48. For cards, the default is one calendar month. For SEPA, the default is 42 days.

Example:

20

connection_options.adyen-card.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-card.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-card.autoRescueScenario

enum<string> | null

The rescue scenario to simulate for a transaction, when autoRescue is set to true.

Available options:

AutoRescueSuccessfulFirst,

AutoRescueSuccessfulSecond,

AutoRescueFailed,

AutoRescueFraud

Example:

"AutoRescueSuccessfulFirst"

connection_options.adyen-card.window_origin

string | null

The origin of the window where the payment is initiated, used for 3D Secure authentication.

Example:

"https://example.com"

connection_options.adyen-card.splits

AdyenSplitsOptions · object

Passes information of splitting payment amounts to the Adyen API.

Show child attributes

connection_options.adyen-card.splits.authorization

Authorization · object[] | null

Split payment values to pass to the Adyen API on payment authorization. See the Adyen docs for details on the format and contents of the list.

connection_options.adyen-card.splits.capture

Capture · object[] | null

Split payment values to pass to the Adyen API on payment capture. See the Adyen docs for details on the format and contents of the list.

connection_options.adyen-card.splits.refund

Refund · object[] | null

Split payment values to pass to the Adyen API on payment refund. See the Adyen docs for details on the format and contents of the list.

connection_options.adyen-cashapp

AdyenOptions · object

Custom options to be passed to the adyen-cashapp connector.

Show child attributes

connection_options.adyen-cashapp.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-cashapp.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-giropay

AdyenOptions · object

Custom options to be passed to the adyen-giropay connector.

Show child attributes

connection_options.adyen-giropay.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-giropay.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-ideal

AdyenOptions · object

Custom options to be passed to the adyen-ideal connector.

Show child attributes

connection_options.adyen-ideal.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-ideal.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-sepa

AdyenSepaOptions · object

Custom options to be passed to the adyen-sepa connector.

Show child attributes

connection_options.adyen-sepa.autoRescue

boolean | null

Set to true to enable Auto Rescue for a transaction. Use the maxDaysToRescue to specify a rescue window.

Example:

true

connection_options.adyen-sepa.maxDaysToRescue

integer | null

Example:

20

connection_options.adyen-sepa.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-sepa.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-sepa.autoRescueSepaScenario

enum<string> | null

The rescue scenario to simulate for a transaction, when autoRescue is set to true.

Available options:

AutoRescueSuccessfulFirst,

AutoRescueSuccessfulSecond,

AutoRescueFailed

Example:

"AutoRescueSuccessfulFirst"

connection_options.adyen-sepa.ownerName

string | null

The name on the SEPA bank account.

Example:

"A. Schneider"

connection_options.adyen-sofort

AdyenOptions · object

Custom options to be passed to the adyen-sofort connector.

Show child attributes

connection_options.adyen-sofort.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-sofort.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.adyen-vipps

AdyenOptions · object

Custom options to be passed to the adyen-vipps connector.

Show child attributes

connection_options.adyen-vipps.additionalData

Additionaldata · object

Passes additional data to the Adyen API when creating a transaction.

Show child attributes

connection_options.adyen-vipps.additionalData.{key}

string

Example:

{ "subMerchantID": "12345" }

connection_options.affirm-affirm

AffirmOptions · object

Custom options to be passed to the affirm-affirm connector.

Show child attributes

connection_options.affirm-affirm.discounts

Discounts · object

Passes additional discounts to the Affirm widget.

Show child attributes

connection_options.affirm-affirm.discounts.{key}

object

Example:

{
  "PRESDAY10": {
    "discount_amount": 1000,
    "discount_display_name": "President's Day 10% off"
  },
  "RETURN5": {
    "discount_amount": 500,
    "discount_display_name": "Returning customer 5% discount"
  }
}

connection_options.affirm-affirm.itinerary

AffirmItineraryOptions · object

Passes itinerary data to the Affirm API.

Show child attributes

connection_options.affirm-affirm.itinerary.type

string | null

The type of itinerary object.

Example:

"flight"

connection_options.affirm-affirm.itinerary.sku

string | null

The booking/itinerary number (if applicable).

Example:

"ABC123"

connection_options.affirm-affirm.itinerary.display_name

string | null

Readable description of the itinerary item.

Example:

"MIA-DCA-2019-12-11T12:07"

connection_options.affirm-affirm.itinerary.venue

string | null

The name of the venue where the event is hosted.

Example:

"Petco Park"

connection_options.affirm-affirm.itinerary.location

string | null

The address object that can be parsed.

Example:

"925 Collins Avenue, Miami Beach, FL, 33140, US"

connection_options.affirm-affirm.itinerary.date_start

string | null

The start date of this itinerary item.

Example:

"2019-12-05"

connection_options.affirm-affirm.itinerary.management

string | null

The corporation.

Example:

"Marriott"

connection_options.braintree-card

BraintreeOptions · object

Custom options to be passed to the braintree-card connector.

Show child attributes

connection_options.braintree-card.discount_amount

integer | null

Passes a discount amount to be applied to the transaction when using Braintree.

Example:

1000

connection_options.braintree-card.custom_fields

Custom Fields · object

Passes customFields to the Braintree API when creating a new payment. Custom fields allow you to customize your checkout experience by collecting specific information about your customers and their purchases.

Show child attributes

connection_options.braintree-card.custom_fields.{key}

string

Example:

{ "checkout": "primary" }

connection_options.braintree-card.dynamic_data_fields

BraintreeDynamicDataFieldsOptions · object

Additional dynamic fields to pass to the Braintree API

Show child attributes

connection_options.braintree-card.dynamic_data_fields.three_ds_auth_status

string | null

Passes the 3DS status to the Braintree API using customFields with the key set to the value of three_ds_auth_status

Example:

"threeDStatus"

connection_options.braintree-card.dynamic_data_fields.purchase_order_number

string | null

Passes the transaction.purchaseOrderNumber field when creating a new transaction.

Example:

"po-12345"

connection_options.braintree-card.dynamic_data_fields.vault_payment_method_criteria

enum<string> | null

Passes the vaultPaymentMethodCriteria field when creating a new transaction.

Available options:

ALWAYS,

ON_SUCCESSFUL_TRANSACTION

Example:

"ON_SUCCESSFUL_TRANSACTION"

connection_options.cybersource-anti-fraud

CybersourceAntiFraudOptions · object

Custom options to be passed to the cybersource-anti-fraud connector.

Show child attributes

connection_options.cybersource-anti-fraud.merchant_defined_data

Merchant Defined Data · object

A list of merchant defined data to be passed to the Cybersource Decision Manager API. Each key needs to be a numeric string.

Show child attributes

connection_options.cybersource-anti-fraud.merchant_defined_data.{key}

string

Maximum string length: 5000

Example:

{ "1": "data" }

connection_options.cybersource-anti-fraud.meta_key_merchant_id

string | null

The merchant ID to use for this transaction. This requires a meta key to be set up for use with Cybersource Decision Manager, and this overrides the connector configuration.

Example:

"merchant-1234"

connection_options.cybersource-anti-fraud.shipping_method

string | null

The shipping method for this transaction.

Example:

"sameday"

connection_options.cybersource-card

CybersourceOptions · object

Custom options to be passed to the cybersource-card connector.

Show child attributes

connection_options.cybersource-card.meta_key_merchant_id

string | null

The merchant ID to use for this transaction. This requires a meta key to be set up for use with Cybersource, and this overrides the connector configuration.

Example:

"merchant-1234"

connection_options.cybersource-card.merchant_defined_information

Merchant Defined Information · object

A list of merchant defined data to be passed to the Cybersource. Each key needs to be a numeric string.

Show child attributes

connection_options.cybersource-card.merchant_defined_information.{key}

string

Example:

{ "1": "data" }

connection_options.cybersource-card.ship_to_method

string | null

The shipping method for this transaction.

Example:

"sameday"

connection_options.cybersource-card.comments

string | null

Brief description of the order or any comment you wish to add to the order.

Example:

"This order is for a new customer"

connection_options.cybersource-ideal

CybersourceOptions · object

Custom options to be passed to the cybersource-ideal connector.

Show child attributes

connection_options.cybersource-ideal.meta_key_merchant_id

string | null

The merchant ID to use for this transaction. This requires a meta key to be set up for use with Cybersource, and this overrides the connector configuration.

Example:

"merchant-1234"

connection_options.cybersource-ideal.merchant_defined_information

Merchant Defined Information · object

A list of merchant defined data to be passed to the Cybersource. Each key needs to be a numeric string.

Show child attributes

connection_options.cybersource-ideal.merchant_defined_information.{key}

string

Example:

{ "1": "data" }

connection_options.cybersource-ideal.ship_to_method

string | null

The shipping method for this transaction.

Example:

"sameday"

connection_options.cybersource-ideal.comments

string | null

Brief description of the order or any comment you wish to add to the order.

Example:

"This order is for a new customer"

connection_options.cybersource-kcp

CybersourceOptions · object

Custom options to be passed to the cybersource-kcp connector.

Show child attributes

connection_options.cybersource-kcp.meta_key_merchant_id

string | null

The merchant ID to use for this transaction. This requires a meta key to be set up for use with Cybersource, and this overrides the connector configuration.

Example:

"merchant-1234"

connection_options.cybersource-kcp.merchant_defined_information

Merchant Defined Information · object

A list of merchant defined data to be passed to the Cybersource. Each key needs to be a numeric string.

Show child attributes

connection_options.cybersource-kcp.merchant_defined_information.{key}

string

Example:

{ "1": "data" }

connection_options.cybersource-kcp.ship_to_method

string | null

The shipping method for this transaction.

Example:

"sameday"

connection_options.cybersource-kcp.comments

string | null

Brief description of the order or any comment you wish to add to the order.

Example:

"This order is for a new customer"

connection_options.dlocal-nequi

DlocalOptions · object

Custom options to be passed to the dlocal-nequi connector.

Show child attributes

connection_options.dlocal-nequi.wallet

DlocalWalletOptions · object

Passes wallet data to the dLocal API for those connectors that need it.

Show child attributes

connection_options.dlocal-nequi.wallet.name

string | null

Passes wallet.name to the dLocal API for those connectors that need it.

Example:

"John Doe"

connection_options.dlocal-nequi.wallet.email

string | null

Passes wallet.email to the dLocal API for those connectors that need it.

Example:

"[email protected]"

connection_options.dlocal-nequi.wallet.token

string | null

Passes wallet.token to the dLocal API for those connectors that need it.

Example:

"123456"

connection_options.dlocal-nequi.wallet.username

string | null

Passes wallet.username to the dLocal API for those connectors that need it.

Example:

"johnd"

connection_options.dlocal-nequi.wallet.verify

boolean | null

Passes wallet.verify to the dLocal API for those connectors that need it.

Example:

true

connection_options.dlocal-upi

DlocalUPIOptions · object

Custom options to be passed to the dlocal-upi connector.

Show child attributes

connection_options.dlocal-upi.wallet

DlocalUPIWalletOptions · object

Passes wallet data to the dLocal API for those connectors that need it.

Show child attributes

connection_options.dlocal-upi.wallet.name

string | null

Passes wallet.name to the dLocal API for those connectors that need it.

Example:

"John Doe"

connection_options.dlocal-upi.wallet.email

string | null

Passes wallet.email to the dLocal API for those connectors that need it.

Example:

"[email protected]"

connection_options.dlocal-upi.wallet.token

string | null

Passes wallet.token to the dLocal API for those connectors that need it.

Example:

"123456"

connection_options.dlocal-upi.wallet.username

string | null

Passes wallet.username to the dLocal API for those connectors that need it.

Example:

"johnd"

connection_options.dlocal-upi.wallet.verify

boolean | null

Passes wallet.verify to the dLocal API for those connectors that need it.

Example:

true

connection_options.dlocal-upi.wallet.recurring_info

DlocalUPIRecurringInfoOptions · object

Passes wallet.recurring_info to the dLocal API for those connectors that need it.

Show child attributes

connection_options.dlocal-upi.wallet.recurring_info.subscription_frequency_unit

enum<string>

required

Indicates the frequency unit for the subscription. Allowed values are: DAY, WEEK, MONTH, BI_MONTHLY, QUARTER, SEMI_ANNUALLY, YEAR, ONDEMAND.

Available options:

MONTH,

WEEK,

BI_MONTHLY,

ONDEMAND,

QUARTER,

YEAR,

SEMI_ANNUALLY,

DAY

connection_options.dlocal-upi.wallet.recurring_info.subscription_frequency

integer

required

Indicates the frequency for the subscription.

connection_options.dlocal-upi.wallet.recurring_info.subscription_start_at

string

required

Indicates the start date for the subscription in format YYYYMMDD.

connection_options.dlocal-upi.wallet.recurring_info.subscription_end_at

string

required

Indicates the end date for the subscription in format YYYYMMDD.

Example:

{
  "subscription_end_at": "20241201",
  "subscription_frequency": 1,
  "subscription_frequency_unit": "MONTH",
  "subscription_start_at": "20231201"
}

connection_options.fiserv-card

FiservOptions · object

Custom options to be passed to the fiserv-card connector.

Show child attributes

connection_options.fiserv-card.installmentOptions

FiservInstallmentOptions · object

Passes installment data to the Fiserv API. This is now also a dedicated feature on the Gr4vy API.

Show child attributes

connection_options.fiserv-card.installmentOptions.numberOfInstallments

integer | null

Passes the order.installmentOptions.numberOfInstallments field to the Fiserv API.

Example:

6

connection_options.fiserv-card.installmentOptions.installmentsInterest

boolean | null

Passes the order.installmentOptions.installmentsInterest field to the Fiserv API.

Example:

true

connection_options.fiserv-card.installmentOptions.installmentDelayMonths

integer | null

Passes the order.installmentOptions.installmentDelayMonths field to the Fiserv API.

Example:

1

connection_options.fiserv-card.installmentOptions.merchantAdviceCodeSupported

boolean | null

Passes the order.installmentOptions.merchantAdviceCodeSupported field to the Fiserv API.

Example:

true

connection_options.forter-anti-fraud

ForterAntiFraudOptions · object

Custom options to be passed to the forter-anti-fraud connector.

Show child attributes

connection_options.forter-anti-fraud.delivery_type

enum<string> | null

The delivery type

Available options:

DIGITAL,

PHYSICAL,

HYBRID

Example:

"DIGITAL"

connection_options.forter-anti-fraud.delivery_method

string | null

The delivery method

Required string length: 1 - 50

connection_options.forter-anti-fraud.is_guest_buyer

boolean | null

Defines if this payment is made using guest checkout.

Example:

true

connection_options.forter-anti-fraud.cart_items

ForterAntiFraudOptionsCartItem · object[] | null

A list of cart items details to pass to the Forter API.

Show child attributes

connection_options.forter-anti-fraud.cart_items.basic_item_data

ForterAntiFraudOptionsCartItemBasicItemData · object

Basic information about the cart item.

Show child attributes

connection_options.forter-anti-fraud.cart_items.basic_item_data.type

enum<string> | null

Indicates whether the item is a physical good or a service/digital item.

Available options:

TANGIBLE,

NON_TANGIBLE

connection_options.forter-anti-fraud.cart_items.delivery_details

ForterAntiFraudOptionsCartItemDeliveryDetails · object

Details about how the item will be delivered.

Show child attributes

connection_options.forter-anti-fraud.cart_items.delivery_details.delivery_type

enum<string> | null

The type of delivery for this cart item.

Available options:

DIGITAL,

PHYSICAL,

HYBRID

connection_options.forter-anti-fraud.cart_items.delivery_details.delivery_method

string | null

The method of delivery for this cart item.

connection_options.forter-anti-fraud.cart_items.beneficiaries

ForterAntiFraudOptionsCartItemBeneficiary · object[] | null

List of beneficiaries who will receive this item.

Show child attributes

connection_options.forter-anti-fraud.cart_items.beneficiaries.personal_details

ForterAntiFraudOptionsCartItemBeneficiaryPersonalDetails · object

required

Personal details of the beneficiary.

Show child attributes

connection_options.forter-anti-fraud.cart_items.beneficiaries.personal_details.first_name

string | null

First name of the beneficiary.

connection_options.forter-anti-fraud.cart_items.beneficiaries.personal_details.last_name

string | null

Last name of the beneficiary.

connection_options.forter-anti-fraud.cart_items.beneficiaries.personal_details.email

string | null

Email address of the beneficiary.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address

ForterAntiFraudOptionsCartItemBeneficiaryAddress · object

Address information of the beneficiary.

Show child attributes

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.country

string

required

The country code of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.address1

string | null

First line of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.address2

string | null

Second line of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.zip

string | null

Zip or postal code of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.region

string | null

State or region of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.company

string | null

Company name associated with the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.address.city

string | null

City of the beneficiary's address.

connection_options.forter-anti-fraud.cart_items.beneficiaries.phone

ForterAntiFraudOptionsCartItemBeneficiaryPhone · object[] | null

Phone numbers associated with the beneficiary.

Show child attributes

connection_options.forter-anti-fraud.cart_items.beneficiaries.phone.phone

string

required

The phone number of the beneficiary.

connection_options.forter-anti-fraud.cart_items.beneficiaries.comments

ForterAntiFraudOptionsCartItemBeneficiaryComments · object

Comments related to the beneficiary.

Show child attributes

connection_options.forter-anti-fraud.cart_items.beneficiaries.comments.user_comments_to_merchant

string | null

Comments from the user to the merchant.

connection_options.forter-anti-fraud.cart_items.beneficiaries.comments.message_to_beneficiary

string | null

Message intended for the beneficiary of the item.

connection_options.forter-anti-fraud.cart_items.beneficiaries.comments.merchant_comments

string | null

Comments from the merchant about this transaction.

connection_options.forter-anti-fraud.total_discount

ForterAntiFraudOptionsDiscount · object

Information about the discount applied to this order.

Show child attributes

connection_options.forter-anti-fraud.total_discount.coupon_code_used

string

required

The coupon code applied to the order.

connection_options.forter-anti-fraud.total_discount.discount_type

string

required

The type of discount applied to the order.

connection_options.forter-anti-fraud.total_discount.coupon_discount_amount

ForterAntiFraudOptionsDiscountCouponDiscountAmount · object

Monetary details of the discount amount.

Show child attributes

connection_options.forter-anti-fraud.total_discount.coupon_discount_amount.amount_usd

string | null

The discount amount in USD.

connection_options.forter-anti-fraud.total_discount.coupon_discount_amount.amount_local_currency

string | null

The discount amount in local currency.

connection_options.forter-anti-fraud.total_discount.coupon_discount_amount.currency

string | null

The currency code for the discount amount.

Example:

"EUR"

connection_options.forter-anti-fraud.total_discount.coupon_discount_percent

string | null

The percentage discount applied via the coupon.

connection_options.gem-gem

LatitudeOptions · object

Custom options to be passed to the gem-gem connector.

Show child attributes

connection_options.gem-gem.promotion_reference

string | null

The promotionReference field passed to the purchase API.

Maximum string length: 128

Example:

"promotion-123"

connection_options.gem-gemds

LatitudeOptions · object

Custom options to be passed to the gem-gemds connector.

Show child attributes

connection_options.gem-gemds.promotion_reference

string | null

The promotionReference field passed to the purchase API.

Maximum string length: 128

Example:

"promotion-123"

connection_options.givingblock-givingblock

GivingBlockOptions · object

Custom options to be passed to the givingblock-givingblock connector.

Show child attributes

connection_options.givingblock-givingblock.defaultCryptocurrency

string | null

The default cryptocurrency to present at checkout. This can be used to ensure the user is presented with the same currency in both your checkout and the Giving Block checkout.

Example:

"BTC"

connection_options.latitude-latitude

LatitudeOptions · object

Custom options to be passed to the latitude-latitude connector.

Show child attributes

connection_options.latitude-latitude.promotion_reference

string | null

The promotionReference field passed to the purchase API.

Maximum string length: 128

Example:

"promotion-123"

connection_options.latitude-latitudeds

LatitudeOptions · object

Custom options to be passed to the latitude-latitudeds connector.

Show child attributes

connection_options.latitude-latitudeds.promotion_reference

string | null

The promotionReference field passed to the purchase API.

Maximum string length: 128

Example:

"promotion-123"

connection_options.mattilda-tapi

MattildaTapiOptions · object

Custom options to be passed to the mattilda-tapi connector.

Show child attributes

connection_options.mattilda-tapi.payment_method_expires_at

string | null

Defines the date at which the payment will expire if not completed. Must be provided in ISO 8601 format (YYYY-MM-DD). If not specified, it defaults to 7 days in the future from the current date.

Example:

"2030-12-01"

connection_options.mattilda-tapifintechs

MattildaTapiOptions · object

Custom options to be passed to the mattilda-tapifintechs connector.

Show child attributes

connection_options.mattilda-tapifintechs.payment_method_expires_at

string | null

Defines the date at which the payment will expire if not completed. Must be provided in ISO 8601 format (YYYY-MM-DD). If not specified, it defaults to 7 days in the future from the current date.

Example:

"2030-12-01"

connection_options.monato-spei

MonatoSpeiOptions · object

Custom options to be passed to the monato-spei connector.

Show child attributes

connection_options.monato-spei.approval_url

string

required

Approval URL that will receive a charge payment method reference.

connection_options.mock-card

MockCardOptions · object

Custom options to be passed to the mock-card connector.

Show child attributes

connection_options.mock-card.merchant_advice_code

MockCardMerchantAdviceCodeOptions · object

Allows for mocking the merchant advice code.

Show child attributes

connection_options.mock-card.merchant_advice_code.account_number

string | null

required

When set, the MAC is only returned if the card number matches this account number.

connection_options.mock-card.merchant_advice_code.result

string | null

The MAC to return for this request.

connection_options.mock-card.skip_retry

boolean | null

When set to true, prevents retries on failed transactions.

connection_options.nuvei-card

NuveiOptions · object

Custom options to be passed to the nuvei-card connector.

Show child attributes

connection_options.nuvei-card.customData

string | null

General data about the customer provided by the merchant.

Maximum string length: 255

Example:

"user=123,trusted=false"

connection_options.nuvei-card.airlineData

NuveiAirlineDataOptions · object

Provides additional airline data for Nuvei payments.

Show child attributes

connection_options.nuvei-card.airlineData.seatClass

string | null

The seat class of the booking

Example:

"F"

connection_options.nuvei-card.airlineData.isCardholderTraveling

boolean | null

Indicates whether the cardholder is also a passenger.

Example:

true

connection_options.nuvei-ideal

NuveiIDealOptions · object

Custom options to be passed to the nuvei-ideal connector.

Show child attributes

connection_options.nuvei-ideal.customData

string | null

Additional data to be sent to Nuvei.

Maximum string length: 255

Example:

"user=123,trusted=false"

connection_options.nuvei-pse

NuveiPSEOptions · object

Custom options to be passed to the nuvei-pse connector.

Show child attributes

connection_options.nuvei-pse.userType

string | null

Customer type ("N" for persona natural, "J" for persona jurídica)

Example:

"N"

connection_options.nuvei-pse.userFisNumber

string | null

Customer’s document type

Example:

"CC"

connection_options.nuvei-pse.fiscalNumber

string | null

Customer’s document number

Example:

"CC"

connection_options.nuvei-pse.bankCode

string | null

The bank code of the selected bank

Example:

"5432"

connection_options.oxxo-oxxo

OxxoOptions · object

Custom options to be passed to the oxxo-oxxo connector.

Show child attributes

connection_options.oxxo-oxxo.payment_method_expires_at

integer | null

Defines a custom expiration time (unix time) after which Oxxo payment requests are cancelled

Example:

1750074293

connection_options.oxxo-oxxo.approval_url

string | null

Approval URL that will receive a charge payment method reference.

Example:

"https://example.com"

connection_options.paypal-paypal

PaypalOptions · object

Custom options to be passed to the paypal-paypal connector.

Show child attributes

connection_options.paypal-paypal.additional_data

Additional Data · object[] | null

Additional Set Transaction Context Values (STC) to be sent to PayPal as part of the transaction.

Show child attributes

connection_options.paypal-paypal.additional_data.{key}

string

Example:

{ "sender_account_id": "customer-1234" }

connection_options.paypal-paypal.shipping

PaypalShippingOptions · object

Shipping information to be passed to the PayPal API.

Show child attributes

connection_options.paypal-paypal.shipping.options

PaypalShippingOptionsItem · object[] | null

Shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Maximum array length: 10

Show child attributes

connection_options.paypal-paypal.shipping.options.id

string

required

A unique ID that identifies a payer-selected shipping option.

Required string length: 1 - 127

connection_options.paypal-paypal.shipping.options.label

string

required

A description that the payer sees, which helps them choose an appropriate shipping option.

Required string length: 1 - 127

connection_options.paypal-paypal.shipping.options.selected

boolean

required

If the API request sets selected = true, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping.options in the PayPal Checkout experience. Only one shipping.option can be set to selected=true.

connection_options.paypal-paypal.shipping.options.type

enum<string> | null

A classification for the method of purchase fulfillment.

Available options:

SHIPPING,

PICKUP,

PICKUP_IN_STORE,

PICKUP_FROM_PERSON

Example:

"SHIPPING"

connection_options.paypal-paypal.shipping.options.amount

PaypalShippingOptionsItemAmount · object

The shipping cost for the selected option.

Show child attributes

connection_options.paypal-paypal.shipping.options.amount.currency_code

string

required

The three-character ISO currency code.

connection_options.paypal-paypal.shipping.options.amount.value

string

required

The amount value, which might include a decimal portion.

Required string length: 1 - 32

Example:

{
  "options": [
    {
      "amount": { "currency_code": "USD", "value": "10.00" },
      "id": "ship_1234",
      "label": "Free Shipping",
      "selected": true,
      "type": "SHIPPING"
    }
  ]
}

connection_options.paypal-paypalpaylater

PaypalOptions · object

Custom options to be passed to the paypal-paypalpaylater connector.

Show child attributes

connection_options.paypal-paypalpaylater.additional_data

Additional Data · object[] | null

Additional Set Transaction Context Values (STC) to be sent to PayPal as part of the transaction.

Show child attributes

connection_options.paypal-paypalpaylater.additional_data.{key}

string

Example:

{ "sender_account_id": "customer-1234" }

connection_options.paypal-paypalpaylater.shipping

PaypalShippingOptions · object

Shipping information to be passed to the PayPal API.

Show child attributes

connection_options.paypal-paypalpaylater.shipping.options

PaypalShippingOptionsItem · object[] | null

Shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Maximum array length: 10

Show child attributes

connection_options.paypal-paypalpaylater.shipping.options.id

string

required

A unique ID that identifies a payer-selected shipping option.

Required string length: 1 - 127

connection_options.paypal-paypalpaylater.shipping.options.label

string

required

A description that the payer sees, which helps them choose an appropriate shipping option.

Required string length: 1 - 127

connection_options.paypal-paypalpaylater.shipping.options.selected

boolean

required

connection_options.paypal-paypalpaylater.shipping.options.type

enum<string> | null

A classification for the method of purchase fulfillment.

Available options:

SHIPPING,

PICKUP,

PICKUP_IN_STORE,

PICKUP_FROM_PERSON

Example:

"SHIPPING"

connection_options.paypal-paypalpaylater.shipping.options.amount

PaypalShippingOptionsItemAmount · object

The shipping cost for the selected option.

Show child attributes

connection_options.paypal-paypalpaylater.shipping.options.amount.currency_code

string

required

The three-character ISO currency code.

connection_options.paypal-paypalpaylater.shipping.options.amount.value

string

required

The amount value, which might include a decimal portion.

Required string length: 1 - 32

Example:

{
  "options": [
    {
      "amount": { "currency_code": "USD", "value": "10.00" },
      "id": "ship_1234",
      "label": "Free Shipping",
      "selected": true,
      "type": "SHIPPING"
    }
  ]
}

connection_options.powertranz-card

PowertranzOptions · object

Custom options to be passed to the powertranz-card connector.

Show child attributes

connection_options.powertranz-card.skipThreeDSecure

boolean | null

default:false

Indicates to PowerTranz whether to skip the 3DS authentication for this transaction.

Example:

true

connection_options.stripe-card

StripeOptions · object

Custom options to be passed to the stripe-card connector.

Show child attributes

connection_options.stripe-card.error_on_requires_action

boolean | null

Passes the error_on_requires_action option to the Stripe API. Set to true to fail the payment attempt if it transitions into requires_action. Use this parameter for simpler integrations that don't handle customer actions, such as saving cards without authentication.

Example:

true

connection_options.stripe-card.stripe_connect

StripeConnectOptions · object

Stripe options to support Stripe Connect

Show child attributes

connection_options.stripe-card.stripe_connect.stripe_account

string | null

The Stripe Connect account to target using the Stripe-Account header.

Example:

"act_123456"

connection_options.stripe-card.stripe_connect.application_fee_amount

integer | null

The fee to charge the connected account.

Example:

"123"

connection_options.stripe-card.stripe_connect.on_behalf_of

string | null

The Stripe Connect account to target using the on_behalf_of request parameter.

Example:

"act_123456"

connection_options.stripe-card.stripe_connect.transfer_data_destination

string | null

The Stripe Connect account to target using the transfer_data.destination request parameter.

Example:

"act_123456"

connection_options.stripe-card.stripe_connect.transfer_group

string | null

A string that identifies the payment as part of a group.

Example:

"ORDER100"

connection_options.travelhub-card

TravelhubOptions · object

Custom options to be passed to the travelhub-card connector.

Show child attributes

connection_options.travelhub-card.customData

TravelHubCustomData · object[] | null

A list of customData to pass to the TravelHub API.

Show child attributes

connection_options.travelhub-card.customData.name

string

required

The key of the custom data field.

connection_options.travelhub-card.customData.value

string

required

The value of the custom data field.

connection_options.travelhub-card.customData.type

string | null

The type of the custom data field.

connection_options.travelhub-card.companyName

string | null

Customer company name to pass to the TravelHub API.

connection_options.trustly-trustly

TrustlyOptions · object

Custom options to be passed to the trustly-trustly connector.

Show child attributes

connection_options.trustly-trustly.refreshSplitToken

boolean | null

Indicates to Gr4vy whether or not the stored Trustly agreement needs refreshing.

Example:

true

connection_options.trustly-trustly.urlScheme

string | null

URL scheme for an app.

Example:

"APP://SOME_RESOURCE"

connection_options.wpay-everydaypay

WpayEverdaypayOptions · object

Custom options to be passed to the wpay-everydaypay connector.

Show child attributes

connection_options.wpay-everydaypay.merchant_defined_data

Merchant Defined Data · object

A dictionary of merchant defined data, to be passed to Wpay for anti-fraud control.

Show child attributes

connection_options.wpay-everydaypay.merchant_defined_data.{key}

string

connection_options.wpay-everydaypay.customerId

string | null

The customer ID for the Everyday Rewards account.

connection_options.wpay-everydaypay.rewardsAccessToken

string | null

The access token for the Everyday Rewards account.

connection_options.wpay-everydaypay.deviceId

string | null

The ID of the device on which the payment is occuring.

connection_options.wpay-everydaypay.postPaymentRedirect

boolean | null

Whether the transaction should redirect post-payment

Example:

true

connection_options.wpay-payto

WpayPaytoOptions · object

Custom options to be passed to the wpay-payto connector.

Show child attributes

connection_options.wpay-payto.instrument

WpayPaytoResourceOptions · object

Options to pass to the instrument resource in the Wpay PayTo API.

Show child attributes

connection_options.wpay-payto.instrument.simulation

WpayPaytoSimulationOptions · object

Simulate responses for this resource.

Show child attributes

connection_options.wpay-payto.instrument.simulation.simulate

string | null

The simulation being requested. Please refer to the developer guide for a list of all available simulations.

connection_options.wpay-payto.instrument.simulation.delay

integer | null

The delay in seconds before the requested simulation is executed.

Example:

5

connection_options.wpay-payto.payment

WpayPaytoResourceOptions · object

Options to pass to the payment resource in the Wpay PayTo API.

Show child attributes

connection_options.wpay-payto.payment.simulation

WpayPaytoSimulationOptions · object

Simulate responses for this resource.

Show child attributes

connection_options.wpay-payto.payment.simulation.simulate

string | null

The simulation being requested. Please refer to the developer guide for a list of all available simulations.

connection_options.wpay-payto.payment.simulation.delay

integer | null

The delay in seconds before the requested simulation is executed.

Example:

5

connection_options.wpay-payto.refund

WpayPaytoResourceOptions · object

Options to pass to the refund resource in the Wpay PayTo API.

Show child attributes

connection_options.wpay-payto.refund.simulation

WpayPaytoSimulationOptions · object

Simulate responses for this resource.

Show child attributes

connection_options.wpay-payto.refund.simulation.simulate

string | null

The simulation being requested. Please refer to the developer guide for a list of all available simulations.

connection_options.wpay-payto.refund.simulation.delay

integer | null

The delay in seconds before the requested simulation is executed.

Example:

5

external_identifier

string | null

The merchant reference for the payment link.

Required string length: 1 - 200

Example:

"external-12345"

statement_descriptor

StatementDescriptor · object

The statement descriptor for the payment link.

Show child attributes

statement_descriptor.name

string | null

Reflects your doing business as (DBA) name.

Required string length: 5 - 22

Example:

"ACME"

statement_descriptor.description

string | null

A short description about the purchase.

Required string length: 5 - 22

Example:

"ACME San Jose Electronics"

statement_descriptor.city

string | null

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

Required string length: 1 - 50

Example:

"San Jose"

statement_descriptor.country

string | null

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

Example:

"US"

statement_descriptor.phone_number

string | null

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

Example:

"+1234567890"

statement_descriptor.url

string | null

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

Required string length: 1 - 50

Example:

"www.example.com"

statement_descriptor.postal_code

string | null

The merchant's postal code or zip code.

Required string length: 1 - 50

Example:

"94560"

locale

string | null

The locale for the payment link.

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

enum<string>

default:authorize

The transaction intent for the payment link.

Available options:

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.

Show child attributes

cart_items.name

string

required

The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.

Required string length: 1 - 255

cart_items.quantity

integer

required

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

Required range: x <= 99999999

cart_items.unit_amount

integer

required

The amount for an individual item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99. The amount sent through to the payment processor as unitary amount will be calculated to include the discount and tax values sent as part of this cart item.

Required range: 0 <= x <= 99999999

cart_items.discount_amount

integer | null

default:0

The amount discounted for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

cart_items.tax_amount

integer | null

default:0

The tax amount for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

cart_items.external_identifier

string | null

An external identifier for the cart item. This can be set to any value and is not sent to the payment service.

Required string length: 1 - 200

Example:

"goprohd"

cart_items.sku

string | null

The SKU or product code for the item.

Required string length: 1 - 200

Example:

"GPHD1078"

cart_items.upc

string | null

The UPC for the item.

Required string length: 1 - 50

Example:

"012345678905"

cart_items.product_url

string | null

The product URL for the item.

Example:

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

cart_items.image_url

string | null

The URL for the image of the item.

Example:

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

cart_items.categories

string[] | null

A list of strings containing product categories for the item.

Required string length: 1 - 50

Example:

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

cart_items.product_type

enum<string> | null

The product type of the cart item.

Available options:

physical,

discount,

shipping_fee,

sales_tax,

digital,

gift_card,

store_credit,

surcharge

Example:

"physical"

cart_items.seller_country

string | null

The seller country of the cart item.

Example:

"US"

cart_items.tax_exempt

boolean | null

Whether the item is exempt of tax.

Example:

false

cart_items.unit_of_measure

string | null

The unit of measure or the unit of measure code.

Required string length: 1 - 50

Example:

"feet"

cart_items.commodity_code

string | null

Item commodity code. Generally a UNSPSC code.

Required string length: 1 - 50

Example:

"43211503"

cart_items.description

string | null

Brief item description.

Required string length: 1 - 255

Example:

"A brief description of an interesting item."

cart_items.duty_amount

integer | null

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

Required range: 0 <= x <= 99999999

Example:

1299

cart_items.shipping_amount

integer | null

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

Required range: 0 <= x <= 99999999

Example:

1299

metadata

Metadata · object

Arbitrary metadata for the payment link.

Example:

{ "order_id": "ORD-12345" }

payment_source

enum<string>

default:ecommerce

The way payment method information made it to this transaction.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

store

boolean

default:false

Whether to store the payment method for future use.

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"

Response

Successful Response

string<uuid>

required

The unique identifier for the payment link.

url

string

required

The URL for the payment link.

amount

integer

required

The amount for the payment link.

Required range: 0 <= x <= 99999999

country

string

required

The country code for the payment link.

currency

string

required

The currency code for the payment link.

intent

enum<string>

required

The transaction intent for the payment link.

Available options:

authorize,

capture

cart_items

CartItem · object[] | null

required

The cart items for the payment link.

Show child attributes

cart_items.name

string

required

The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.

Required string length: 1 - 255

cart_items.quantity

integer

required

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

Required range: x <= 99999999

cart_items.unit_amount

integer

required

Required range: 0 <= x <= 99999999

cart_items.discount_amount

integer | null

default:0

The amount discounted for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

cart_items.tax_amount

integer | null

default:0

The tax amount for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 USD cents represents $12.99.

Required range: 0 <= x <= 99999999

Example:

0

cart_items.external_identifier

string | null

An external identifier for the cart item. This can be set to any value and is not sent to the payment service.

Required string length: 1 - 200

Example:

"goprohd"

cart_items.sku

string | null

The SKU or product code for the item.

Required string length: 1 - 200

Example:

"GPHD1078"

cart_items.upc

string | null

The UPC for the item.

Required string length: 1 - 50

Example:

"012345678905"

cart_items.product_url

string | null

The product URL for the item.

Example:

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

cart_items.image_url

string | null

The URL for the image of the item.

Example:

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

cart_items.categories

string[] | null

A list of strings containing product categories for the item.

Required string length: 1 - 50

Example:

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

cart_items.product_type

enum<string> | null

The product type of the cart item.

Available options:

physical,

discount,

shipping_fee,

sales_tax,

digital,

gift_card,

store_credit,

surcharge

Example:

"physical"

cart_items.seller_country

string | null

The seller country of the cart item.

Example:

"US"

cart_items.tax_exempt

boolean | null

Whether the item is exempt of tax.

Example:

false

cart_items.unit_of_measure

string | null

The unit of measure or the unit of measure code.

Required string length: 1 - 50

Example:

"feet"

cart_items.commodity_code

string | null

Item commodity code. Generally a UNSPSC code.

Required string length: 1 - 50

Example:

"43211503"

cart_items.description

string | null

Brief item description.

Required string length: 1 - 255

Example:

"A brief description of an interesting item."

cart_items.duty_amount

integer | null

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

Required range: 0 <= x <= 99999999

Example:

1299

cart_items.shipping_amount

integer | null

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

Required range: 0 <= x <= 99999999

Example:

1299

Example:

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

payment_source

enum<string>

required

The way payment method information made it to this transaction.

Available options:

ecommerce,

moto,

recurring,

installment,

card_on_file

created_at

string<date-time>

required

The date and time the payment link was created.

updated_at

string<date-time>

required

The date and time the payment link was last updated.

status

enum<string>

required

The status of the payment link.

Available options:

active,

completed,

expired,

processing

type

string

default:payment-link

Always payment-link.

Allowed value: "payment-link"

expires_at

string<date-time> | null

The expiration date and time for the payment link.

Example:

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

external_identifier

string | null

The merchant reference for the payment link.

Required string length: 1 - 200

Example:

"external-12345"

statement_descriptor

StatementDescriptor · object

The statement descriptor for the payment link.

Show child attributes

statement_descriptor.name

string | null

Reflects your doing business as (DBA) name.

Required string length: 5 - 22

Example:

"ACME"

statement_descriptor.description

string | null

A short description about the purchase.

Required string length: 5 - 22

Example:

"ACME San Jose Electronics"

statement_descriptor.city

string | null

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

Required string length: 1 - 50

Example:

"San Jose"

statement_descriptor.country

string | null

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

Example:

"US"

statement_descriptor.phone_number

string | null

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

Example:

"+1234567890"

statement_descriptor.url

string | null

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

Required string length: 1 - 50

Example:

"www.example.com"

statement_descriptor.postal_code

string | null

The merchant's postal code or zip code.

Required string length: 1 - 50

Example:

"94560"

locale

string | null

The locale for the payment link.

Example:

"en"

merchant_name

string | null

The merchant's display name.

Required string length: 1 - 100

Example:

"ACME Inc."

merchant_url

string | null

The merchant's website URL.

Example:

"https://merchant.example.com"

merchant_banner_url

string | null

The merchant's banner image URL.

Example:

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

merchant_color

string | null

The merchant's brand color.

Required string length: 1 - 100

Example:

"#FF5733"

merchant_message

string | null

A message from the merchant.

Required string length: 1 - 255

Example:

"Thank you for your purchase!"

merchant_terms_and_conditions_url

string | null

URL to the merchant's terms and conditions.

Example:

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

merchant_favicon_url

string | null

URL to the merchant's favicon.

Example:

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

return_url

string | null

The return URL after payment completion.

Example:

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

metadata

Metadata · object

Arbitrary metadata for the payment link.

Example:

{ "order_id": "ORD-12345" }

buyer

TransactionBuyer · object

The buyer associated with the payment link.

Show child attributes

buyer.type

string

default:buyer

Always buyer.

Allowed value: "buyer"

buyer.id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

buyer.display_name

string | null

The display name for the buyer.

Required string length: 1 - 200

Example:

"John Doe"

buyer.external_identifier

string | null

The merchant identifier for this buyer.

Required string length: 1 - 200

Example:

"buyer-12345"

buyer.billing_details

BillingDetails · object

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

Show child attributes

buyer.billing_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

buyer.billing_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

buyer.billing_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

buyer.billing_details.phone_number

string | null

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

Example:

"+1234567890"

buyer.billing_details.address

Address · object

The billing address for the buyer.

Show child attributes

buyer.billing_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

buyer.billing_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

buyer.billing_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

buyer.billing_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

buyer.billing_details.address.state_code

string | null

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

Example:

"US-CA"

buyer.billing_details.address.house_number_or_name

string | null

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

Required string length: 1 - 255

Example:

"10"

buyer.billing_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

buyer.billing_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

buyer.billing_details.address.organization

string | null

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

Required string length: 1 - 255

Example:

"Gr4vy"

buyer.billing_details.tax_id

TaxId · object

The tax ID information associated with the billing details.

Show child attributes

buyer.billing_details.tax_id.value

string

required

The tax ID for the buyer.

Required string length: 1 - 50

buyer.billing_details.tax_id.kind

enum<string>

required

The kind of tax ID

Available options:

ae.trn,

au.abn,

ar.dni,

ar.cuil,

ar.cuit,

br.cnpj,

br.cpf,

ca.bn,

ca.gst_hst,

ca.pst_bc,

ca.pst_mb,

ca.pst_sk,

ca.qst,

ch.vat,

cl.tin,

co.itin,

co.nit,

es.cif,

eu.vat,

gb.vat,

hk.br,

id.nik,

id.npwp,

in.gst,

in.pan,

jp.cn,

jp.rn,

kr.brn,

li.uid,

mx.curp,

mx.rfc,

my.frp,

my.itn,

my.nric,

my.sst,

no.vat,

nz.gst,

pe.ruc,

ph.tin,

ru.inn,

ru.kpp,

sa.vat,

sg.gst,

sg.uen,

th.id,

th.vat,

tw.vat,

us.ein,

za.vat,

bo.ci,

uy.rut,

uy.ci

buyer.account_number

string | null

The buyer account number.

Required string length: 1 - 200

shipping_details

ShippingDetails · object

The shipping details for the payment link.

Show child attributes

shipping_details.first_name

string | null

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

Required string length: 1 - 255

Example:

"John"

shipping_details.last_name

string | null

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

Required string length: 1 - 255

Example:

"Doe"

shipping_details.email_address

string | null

The email address for the buyer.

Required string length: 1 - 320

Example:

"[email protected]"

shipping_details.phone_number

string | null

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

Example:

"+1234567890"

shipping_details.address

Address · object

The billing address for the buyer.

Show child attributes

shipping_details.address.city

string | null

The city for the address.

Required string length: 1 - 100

Example:

"San Jose"

shipping_details.address.country

string | null

The country for the address in ISO 3166 format.

Example:

"US"

shipping_details.address.postal_code

string | null

The postal code or zip code for the address.

Required string length: 1 - 50

Example:

"94560"

shipping_details.address.state

string | null

The state, county, or province for the address.

Required string length: 1 - 255

Example:

"California"

shipping_details.address.state_code

string | null

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

Example:

"US-CA"

shipping_details.address.house_number_or_name

string | null

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

Required string length: 1 - 255

Example:

"10"

shipping_details.address.line1

string | null

The first line of the address.

Required string length: 1 - 255

Example:

"Stafford Appartments"

shipping_details.address.line2

string | null

The second line of the address.

Required string length: 1 - 255

Example:

"29th Street"

shipping_details.address.organization

string | null

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

Required string length: 1 - 255

Example:

"Gr4vy"

shipping_details.id

string<uuid> | null

The ID for the shipping details.

Example:

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

shipping_details.buyer_id

string<uuid> | null

The ID for the buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

shipping_details.type

string

default:shipping-details

Always shipping-details.

Allowed value: "shipping-details"

connection_options

Connection Options · object

The connection options for the payment link.

Show child attributes

connection_options.{key}

object

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"

Introduction

Transactions

Buyers

Checkout Sessions

Payment links

Payment options

Payouts

Refunds

Sessions

Settlement records

Disputes

Instruments

Vault

Connections

Errors

Other

Add a payment link

Authorizations

Headers

Body

Response