Payment links

Payment links allows generation of a link, to send to a customer via email/sms/etc, and then have the customer pay without the need to host a custom checkout.

Creating a payment link

Use the payment links endpoint to create a payment link with the data displayed on the hosted page. The payment links API endpoint makes it easy to get create a new payment link.

{
  "currency":"AUD",
  "country":"AU",
  "amount":1000,
  "metadata":{
    "TypeOfPayment":"purchase",
    "Carbon_FootPrint":"10"
  },
  "cart_items":[
    {
      "name":"Aloe",
      "unit_amount":1000,
      "quantity":1,
      "sku":"aloe"
    }
  ],
  "merchant_banner_url":"https://susies.store/logo.svg",
  "merchant_color":"#cf6b6b",
  "merchant_name":"Susie's Store",
  "merchant_url":"https://susies.store",
  "merchant_message":"Thanks for your purchase at Susie's Store!",
  "merchant_terms_and_conditions_url":"https://susies.store/terms-and-conditions",
  "return_url":"https://susies.store/success"
}

The payment link includes the expires_at, status, and other useful information used by the hosted page. Make note of the returned id as it is used in the next step.

{
    "id": "09e90ace-a746-41f5-88d2-8b16335ded97",
    "type": "payment-link",
    "expires_at": "2025-01-28T14:45:45.929102+00:00",
    "amount": 1000,
    "currency": "AUD",
    "country": "AU",
    "status": "active",
    ...
}

The hosted page passes these fields to Embed, which uses them to create the transaction:

amount, currency, and country (required)
buyer
buyer_id
cart_items
connection_options
external_identifier
installment_count
intent
metadata
payment_source
statement_descriptor
store

These fields control the hosted page itself:

expires_at sets when the link expires. See expiration.
locale sets the language of the page.
return_url is where the page sends the customer once the transaction is created, whatever its outcome. Gr4vy appends gr4vy_transaction_id and gr4vy_transaction_status. Without it, the page shows its own confirmation screen.
merchant_name, merchant_url, merchant_banner_url, merchant_color, merchant_message, merchant_terms_and_conditions_url, and merchant_favicon_url brand the page. When you set both merchant_name and merchant_url, the success and expired screens show a Return to link with your merchant name that opens merchant_url.

See the API reference for the full list of fields. By creating a payment link, send it to the customer to complete the payment.

Set the intent

intent sets the initial state of the transaction that the payment link creates. It accepts authorize, which is the default, capture, or prefer_authorize. prefer_authorize authorizes the payment where the payment service supports delayed capture, and captures it where it doesn’t. It’s the payment link equivalent of the Embed preferAuthorize option. The spelling differs on purpose: the API uses snake_case, so the payment link value is prefer_authorize. A payment link’s intent and its transaction’s intent are different things:

A transaction created from a prefer_authorize link always reports its intent as authorize or capture, never prefer_authorize.
The payment link keeps the intent it was created with, so the payment-link.created and payment-link.updated webhooks can carry "intent": "prefer_authorize".

Add airline data

To send airline travel data to the payment service, set the airline object when you create the payment link. It uses the same schema as airline on create transaction, so it can describe several passengers and several flight legs.

POST /payment-links

{
  "amount": 84000,
  "currency": "USD",
  "country": "US",
  "intent": "authorize",
  "airline": {
    "booking_code": "X36Q9C",
    "passenger_name_record": "LUHN/JOHN",
    "ticket_number": "123-1234151555",
    "issuing_iata_designator": "XX",
    "passengers": [
      { "first_name": "John", "last_name": "Luhn", "age_group": "adult", "ticket_number": "123-1234151555" },
      { "first_name": "Jane", "last_name": "Luhn", "age_group": "adult", "ticket_number": "123-1234151556" }
    ],
    "legs": [
      { "iata_designator": "XX", "flight_number": "101", "departure_airport": "JFK", "arrival_airport": "LHR", "departure_at": "2027-01-10T19:00:00+00:00" },
      { "iata_designator": "XX", "flight_number": "102", "departure_airport": "LHR", "arrival_airport": "JFK", "departure_at": "2027-01-24T11:00:00+00:00" }
    ]
  }
}

When the customer pays the link, Gr4vy copies the airline data onto the transaction and sends it to the payment service at authorization, including after 3DS. If you capture later without an airline object, Gr4vy sends the stored airline data with the capture.

The airline data on the payment link takes precedence over any airline object sent when the transaction is created.
You can’t change the airline data after you create the payment link.
Get payment link and list payment links return the airline object. The hosted page never receives or shows it, so the customer doesn’t see passenger details.
Connections that accept airline data, such as Nuvei and Worldline TravelHub, forward it to the payment service. Other connections ignore it.

Limit the payment methods on a link

Payment links don’t take a list of payment methods to show or hide. To control which methods appear, set a metadata key on the payment link, for example {"link_type": "invoice"}, and add a rule to the Checkout Flow with a Metadata condition on that key. The rule then selects the payment options for those links. If no rule matches, the page shows all configured and active payment options. Checkout Flow rules apply to the whole merchant account, not just to payment links.

Storing a payment method

A payment link can be used to securely store a payment method against a buyer’s profile. To do this, you need to pass both the buyer_id and store parameters. When store is set to true, the buyer_id of an existing buyer must also be provided. After the payment is completed, the payment method used is stored and associated with that buyer. When store is true, the payment link page only shows payment methods that can be stored, so some of the options you’ve configured might not appear. Currently, it is not possible to use a buyer’s existing stored payment methods to complete a payment link.

Zero-amount links

You can create a payment link with an amount of 0. With store set to true, the link stores the buyer’s payment method. With store set to false, the link only verifies the payment method and doesn’t store it. A zero-amount link only offers payment services that support zero-amount authorization.

When buyer_id is provided, the URL of the payment link should be treated as a secret as it allows anyone the ability to manage payment methods for the associated buyer.

Find a payment link’s transactions

To list the transactions created through a payment link, call list transactions with the payment_link_id query parameter set to the id of the payment link.

GET /transactions?payment_link_id=09e90ace-a746-41f5-88d2-8b16335ded97

In the dashboard, go to Transactions > Payment links and open the payment link to see its transactions.

Get started

Integration guides

Best Practices

Resources

Features

Other

Creating a payment link

Set the intent

Add airline data

Limit the payment methods on a link

Storing a payment method

Zero-amount links

Find a payment link’s transactions